Plugin Developer Guide

So you want to write a plugin?! You came to the right place!

Modify the default plugin

The easiest way to create a plugin is to modify the existing one. Open this file:

plugins/siriproxy-example/lib/siriproxy-example.rb

You can see a simple structure of how Siri intercepts voice commands. The syntax is:

listen_for /regular expression/i do
    say something
    request_completed
end

When you speak to Siri, it matches the captured text against the regular expressions you specify with each "listen_for". See later in this document for some Ruby regular expression tricks if you aren't familiar with Ruby syntax.

Try changing this line:

  listen_for /test siri proxy/i do

to:

  listen_for /hello siri proxy/i do

Installing your plugin

After modifying the default plugin, stop your Siri server (Ctrl-C). In your Siri root directory (not .siriproxy, but the root of your Siri proxy checkout) run:

siriproxy update .

The '.' is required because otherwise the update will go out to Github to find things. This isn't documented anywhere, so hopefully you found this page! T

Start up your Siri proxy server again with:

siriproxy server

Now test it out! Use your phone to say "hello siri proxy". If you get the correct response, it works! Congratulations!

Publishing your plugin for others to install

Push your plugin to a repository here on github, name it siriproxy-YourPluginsName, make sure you have a config.yml file that has exactly what you would put into your proxy's config.yml to load your plugin from your github repo, and then go to the Plugins page and click on edit to add your plugin there. Just copy the format of the other plugins listed there and then save the Plugins page and you're done!

Regex tips

Ruby regexes are similar to other languages. If you are not familiar with a regular expression, go read up on it, because you won't be able to develop a plugin without that knowledge.

To specify a capture group:

listen_for /siri proxy word ([a-z]*)/i do |word|

listen_for /siri proxy number ([0-9,]*[0-9])/i do |number|

To specify multiple capture groups (test this by saying "siri proxy word hello number three"):

listen_for /siri proxy word ([a-z]*) number ([a-z]*)/i do |word, number|

SUPER IMPORTANT NOTE: Why did we make "number" a letter group instead of digits? It's because nothing magic happens when you say a number. Siri will interpret you saying "three" as the word "three". The exception to this is if you say a string of numbers like "four five six" Siri will interpret that as "456".

To specify optional words:

listen_for /how do I get to(?: the)? store/i do

There are two important things in the above statement. First, the ?: in the group means it will not capture, so you don't need to add a |capture| after the do. If you want to capture the optional word, remove the ?:. The second important thing is the space is IN the capture group. If you just did this:

listen_for /how do I get to (?:the)? store/i do

And you said "how do I get to store" to Siri, it wouldn't match, because the regex would be looking for two spaces, one before the group and one after. Tricky and stupid stuff!

To make siri say something she doesn't write:

say "Sometimes I don't write what I say", spoken: "Sometimes I don't say what I write"

Whatever is in the 'spoken' part of the statement is what siri will speak to the user. Whatever is in the 'say' part is what siri writes to the user

Passing configuration options to your plugin

In order to load config options such as API keys to use certain databases (ie: the Punchfork database, which already has a plugin), or login information like the google voice plugin, or all those consumer keys etc. like what you need for the Twitter plugin, or whatever other reason you need/want to load a configuration option you to your plugin, you'll have to:

Have a unique name for the config option you'll be using and you will need to put this in your config.yml for your proxy. Like this:

   -name: 'PluginName'
    git: 'git://github.com/Username/siriproxy-PluginName.git'
    apikey_for_PluginName: 'thisistheapikey'

In your plugin code you'll need an initializing method that goes through the config and gets your apikey to use for the plugin. Your code will look something like this:

def initialize(config)
   apikey = config['apikey_for_PluginName']
end

Now you can use the variable apikey in your plugin however you need.

Making Siri remember things

TODO

Troubleshooting

If you get this when starting up Siri proxy:

rescue in block in initialize': Cannot start the server on port 443

Run this command to find out which programs are listening on port 443:

sudo lsof -i:443

Then get their PIDs (you probably only need to kill ruby) from the PID column and kill them with:

sudo kill -9 xxxx

This page is a work in progress. Feel free to edit it.