URL-Calling-Scheme

iPeng from 1.3.4 / 1.1.4 (iPad) on is callable from other Apps through a URL scheme.

iPeng 7/8/9 have more advanced capabilities, if you need deeper integration e.g. with home automation apps please have a look at the advanced scheme below.

The Simple Call

This is what will be supported from iPeng 1.3.4/1.1.4 on

URL Handler

iPeng registers a handler for

ipeng:

sbox:

iPeng 7 also registers a handler for

ipeng7:

Instead of sbox: iPeng UE registers a handler for

ueradio:

Simple Scheme Including a Music Link

The general scheme is

ipeng:<URL including protocol>

Parameter Description:

<URL including protocol> 

A URL that is understood by Squeezebox Server or iPeng, so this can be a file URL or an App URL like „spotify://…“.
Use is currently limited to what Squeezebox Server supports, that means single tracks or streams.
iPeng will open a context menu and ask what to do with the element.
If no URL is specified, iPeng will do nothing.

iPeng understands the following schemes and services:

Protocols:

lfm://
napster://
rhapd://
rtsp://
spotify:, spotify://, spotifyradio:, spotifyradio://
slacker://
wimp://
youtube://

Services and their URL Ranges (http://)

This of course only applies to playable links.

  • Spotify (open.spotify.om)
  • [wiki:YouTube YouTube (youtube.com)]
  • Last.fm (lastfm.<country> or last.fm)
  • Pandora (pandora.com)
  • Slacker (slacker.com)
  • Napster (napster.com)
  • Rhapsody (rhapsody.com)
  • WiMP (wimp.no and wimp.dk)

More Capabilities

Since iPeng 2.0.9/1.4.9, an „sboxplayer“ command is supported to select a player to be used.

?sboxplayer=<MAC>

to the URL that’s used to call iPeng.

Parameter Description:

<MAC>

A player the action should be executed on. If omitted, iPeng will use the current player.

Advanced Scheme in iPeng 7/8/9

From version 7.0.2 on , iPeng supports the standardized x-callback URL calling scheme.
http://x-callback-url.com/

To support this, iPeng registers an additional handler:

ipeng-x-callback://

This handler supports the x-callback URL-scheme:

ipeng-x-callback://x-callback-url/[action]?[x-callback parameters]&[action parameters]

This handler does NOT use the syntax described in the „simple“ sections above but the standardized x-callback format.

Parameter Description:

action

The following values for action are supported:

No action (empty) – just open App, define a return-url and/or select a player
urlmenu open a URL provided in the „url“ parameter

The following parameters for the other fields are supported with x-callback, all of them are optional with the exception of the „url“ parameter for the urlmenu-action:

x-source=<name> – Name of source App
x-success=<url> – Return-URL to be used by return menu. If this is being supplied, iPeng will show a menu item to return to the calling App in it’s main menu
sboxplayer=<MAC> – Player to be used
url=<url> – URL to be used with the urlmenu action
urltitle=<name> – Name for the playable URL provided. This is meant to supply a readable title for the context menu opened to play the URL

Note: A „url=“ parameter needs to be the last parameter in the list. All subsequent parameters will be ignored
Note 2: An „x-success=“ URL must not include parameters or query strings. If it does, these will be ignored and not called.