Porthole is now scriptable

June 2014

Porthole version 1.7.0 came out two days ago. It introduces scripting, a feature that’s been requested more than once.

Being able to use AppleScript to control Porthole means that you can automate and toggle certain functions of Porthole without going through the interface. Which is pretty awesome!

Script Porthole using AppleScript

Update to the latest version from within the app, or download a fresh copy from the website. Then read the tutorial on scripting to get started.

Learn How to Script Porthole

June 2014

Starting with version 1.7.0 Porthole is scriptable using Apple’s AppleScript Editor (or Script Editor in Yosemite). This means that you can automate and toggle certain functions of Porthole without going through the interface.

Index

  1. Use cases
  2. Getting started
  3. Advanced tricks
  4. Notifications
  5. Reference

Use cases

These are a few cases in which scripting could come in handy:

  • Automatically connecting to a certain (or every) speaker on startup.
  • Chaining several actions in one, such as: starting Spotify, playing a song and then connecting to all your AirPlay devices. You can put that in a single script.
  • You could use it to develop a remote control.
  • And obviously any case where you want to control Porthole without going through the interface.

Getting started

  • Launch Porthole at least once and set it up.
  • Start (Apple)Script Editor.app (find it in /Applications/Utilities/(Apple)Script Editor.app).

Script Editor

When you have AppleScript Editor running, paste in the script below to get the name of the first speaker Porthole’s found. Press the big green “Run” button when you’re done.

tell application "Porthole"
  name of first speaker
end tell

As you were probably expecting, Porthole should now be connected to the first speaker it found. Pretty sweet!

Advanced tricks

Say that you always want to connect to a certain speaker when your Mac boots up. There are a few things we need to do for this to work:

  1. Get a unique identifier for our speaker.
  2. Use that unique identifier to connect to the specific speaker.
  3. Run the script on startup.

Getting the unique identifier

Run this script:

tell application "Porthole"
  set output to "Speakers:\n"
  repeat with sp in speakers as list
    set output to output & id of sp & ": " & name of sp & "\n"
  end repeat
end tell

It should return something along the lines of this:

"Speakers: 
12AB34CD56EF: Boy & Auk's AirPort Express
FE65DC43BA21: AirPort Express
"

Using the unique identifier

he first value is the MAC address and unique identifier of the speaker, we’ll use this to pick out a specific speaker to connect to.Let’s pick “Boy & Auk’s AirPort Express” in this case. Make sure you replace the id with the value that was returned on your Mac.

tell application "Porthole"
  set sp to (first speaker whose id is "12AB34CD56EF")
  if sp is not connected then
    connect to sp
  end if
end tell

And that’s it, Porthole will only connect to that specific speaker. Run the script to test it.

Run the Script on Startup

You can actually turn Scripts into Applications, which you can add to your Login Items. Perfect, exactly what we need. Before we do this though, lets make a tiny modification to our script.

tell application "Porthole"
  activate
  delay 10
  set sp to (first speaker whose id is "12AB34CD56EF")
  if sp is not connected then
    connect to sp
  end if
end tell

The ‘activate’ command will load Porthole if it isn’t already running. Then the delay will give Porthole ten seconds to discover any available speakers. After that the script runs like it did before.

To turn this into an app, in (Apple)Script Editor, click File → Export… and in the dialog box that opens choose Application under File Format.

Save the file anywhere you like, but remember its location.

Finally, go into System Preferences and select Users & Groups, then Login Items. Press the little + button and pick the Application you just created. Your script will now run at login!

Notifications

Version 1.7.1 and up.

Porthole sends out system wide notifications when an AirPlay speaker appears/disappears/connects/disconnects and when the computer speaker setting is toggled. This removes the need to poll for changes.

To receive these notifications, hook into the NSDistributedNotificationCenter event:

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    // Insert code here to initialize your application
    [[NSDistributedNotificationCenter defaultCenter] addObserver:self selector:@selector(handlePortholeSpeakerStateChanged:) name:@"com.dangercove.Porthole.SpeakerStateChanged" object:nil];
}

- (void)dealloc {
    [[NSDistributedNotificationCenter defaultCenter] removeObserver:self];
}

- (void)handlePortholeSpeakerStateChanged:(NSNotification *)notification {
    NSLog(@"Speaker state changed:\n%@", notification.userInfo);
}

The notification’s userInfo contains a dictionary with the current speaker setup:

{
    speakers =     (
                {
            connected = 1;
            macaddress = 12AB34CD56EF;
            name = "Danger Cove";
        },
                {
            connected = 1;
            macaddress = AB34CD56EF12;
            name = SandroTV;
        },
                {
            connected = 0;
            macaddress = FE65DC43BA21;
            name = "AirPort Express";
        }
    );
    useComputerSpeaker = 0;
}

Reference

These are all the Porthole-specific commands you can use. For a more general AppleScript tutorial, have a look at this guide.

Parameter Description
speaker Addresses a single speaker. Properties: id, name, connected, streaming
every speaker Addresses all speakers.
first/second/…/last speaker Addresses the first/second/etc speaker. You can also use speaker 1,2,3,etc.
connect to [speaker(s)] Connect to the specified speaker(s).
disconnect from [speaker(s)] Disconnect from the specified speaker(s).

General

Command Description
use computer speaker [boolean] Enable or disable the (connected) computer speaker.

This is a property. You can set like so:

tell application "Porthole"
  set use computer speaker to true -- or false
end tell

Easily add acknowledgments to your Xcode projects

May 2014

When you’re working on a iOS or OSX app, you’re bound to use a library, framework or other code that was generously shared by other people. The right thing to do (especially when the license requires it!) is to acknowledge that you’re using their work in your app.

There are various ways to go about this, but I’ve just released a script called Acknowledge that will make it very easy. It also works very well with DCOAboutWindow, which I released earlier.

![Acknowledgments] /assets/img/old/content/acknowledge-acknowledgments.jpg)

Acknowledge is a simple bash script that will easily generate a rtf that contains all the acknowledgments for libraries, frameworks and other code you’ve used in your iOS or OSX project.

It’s made to work very well with DCOAboutWindow and Cocoapods. Acknowledge relies on MultiMarkdown by Fletcher Penny.

You can read more about Acknowledge on GitHub, or follow the setup guide below.

Clone

Clone the repo, preferably into the root of your Xcode project:

$ git clone git@github.com:DangerCove/Acknowledge.git

Or if your project is a repo already, add it as a submodule:

$ git submodule add git@github.com:DangerCove/Acknowledge.git

Install multimarkdown

Follow the guide on Fletcher’s website, or if you’re using homebrew:

$ brew install multimarkdown

Configure

Copy acknowledge.cfg.default to acknowledge.cfg:

$ cd Acknowledge
$ cp acknowledge.cfg.default acknowledge.cfg

Customize the paths to multimarkdown and your Pods folder if necessary.

Add acknowledgments

If you use Cocoapods and have your Pods directory setup, you are ready to go. Just run acknowledge.

$ ./acknowledge

Other acknowledgments

Just add a markdown file to the sources directory and Acknowledge will handle the rest. Make sure the extension is .md.

Order

You might’ve notice the 10_ and 20_ prefixes in front of the files in the sources folder. Acknowledge will concatenate the files in order, so just add files and change to number to change the order.

The acknowledgments generated by Cocoapods will always be prepended with 10_.

Potential directory layout

.
|- Acknowledge/
|   |- acknowledge
|   |- ...
|   |- source/
|   |   |- 11_Vendor.md
|   |   |- 20_Acknowledge.md
|- Pods/
|   |- Pods-acknowledgements.markdown
|-  |- ...
|- Podfile
|- Coolproject.xcodeproj
|- Coolproject.xcworkspace
|- ...

Test it

Don’t skip this step, you’ll need to output in the next one.

Open a terminal window and run acknowledge once to see if it works, and to generate the initial Acknowledgments.rtf.

$ ./acknowledge

Fix any errors and proceed.

Add it to Xcode

You’ll probably want to show the acknowledgments somewhere in your app (have a look at DCOAboutWindow if you’re working on a Mac app, btw).

Simply add the generated Acknowledgments.rtf file to your project and display it somewhere.

Generate the acknowledgments on each build

Keeping your acknowledgments up to date is easy if you add Acknowledge as a build phase. Here’s how that works:

  1. Open Xcode;
  2. Select your project and open the Build Phases tab;
  3. Click Editor → Add Build Phase → Add Run Script Build Phase;
  4. Name your script something like “Update Acknowledgments” and position it so that it’s above Copy Bundle Resources;
  5. Now add the following code:

cd Acknowledge && ./acknowledge

(Make sure to adapt the paths if the script isn’t located in the default folder.)

It should look something like this:

Acknowledge build phase

That’s it! Just build your project and you’re set.

So much (volume) control

April 2014

Porthole volume control

Porthole’s main volume control has always been the buttons on the keyboard. Pressing F10 will mute everything, F11 lowers it and F12 turns it up. Just as you’d expect when looking at the little icons on the keys, really.

Sometimes this isn’t enough. Looking at the amount of votes this got on the suggestion page, for quite a few people this wasn’t enough. If you have a great deal of speakers around your home (or one that’s particularly obnoxious, volume wise) being able to set a specific volume becomes important.

This posed a design challenge, more than a technical one. I frankly didn’t feel comfortable adding an undetermined number of sliders to the interface. Porthole’s main focus has always been elegance and ease of use. That doesn’t mix well with a row of sliders, trust me. Also, I didn’t want to give up the use of the volume keys.

After some consideration and tests, I came up with something that works. There are sliders, but they aren’t in the main interface and they control the volume, but not in a way that conflicts with the volume keys. Instead of setting the volume absolutely, the sliders determine an offset, that’s why you can set a negative number.

In practice, this works as follows: Say the main volume is at 5, one speaker has a -2 offset, the other +4. This means the absolute volume for speaker one is 3 and for the other 9. Pressing the volume keys to turn up the volume by 1, sets the speakers to 4 and 10 respectively.

This might take a bit to get used to, but I’ve found it works very very well. Especially because all volume preferences are saved per speaker.

Want to take this for a spin? Just download version 1.6.0 or higher!

VLC 2.1.3 fixes AirPlay trouble

February 2014

In the first two releases of VLC 2.1.x, AirPlay wasn’t working like it’s supposed to. I even recommended to stay on 2.0.8 if you wanted to use AirVLC.

With the recent release of version 2.1.3 all problems seem to have been fixed and AirVLC is compatible out of the box! You can update VLC from within the app, or through their website.