JSON RPC

From DevWiki

Jump to: navigation, search

Contents

Overview

JSON RPC is a raw TCP Socket interface for communicating with Boxee. It replaces the soon-to-be-depreceated HTTP API, and offers a more secure and robust mechanism in the same format. It is based upon the JSON RPC 2.0 specification.

Accessing this API requires that the caller is "paired" with Boxee. Once a devices/application is paired with Boxee, it can connect and get access to the Boxee APIs.

Each method in the interface can have different security needs which means one client may be allowed to only control playback while another can only read and manipulate the library. In this version all clients are granted full authority (after pairing). The design of JSON RPC is that most methods should behave roughly the same and maintain consistency while hiding the mechanics of boxee from the client creator.

The Boxee API tries to follow the XBMC API as close as possible to enable developers to share code between applications that control XBMC and applications that control Boxee.

Note: future versions might include support for JSON RPC over HTTP, the current version support only raw TCP. Raw TCP is more useful since it supports notifications.

Discovery

Zeroconf/Avahi/Bonjour can be used to discover the Boxee client and the JSON-RPC TCP port. It is identified by:

_boxee-jsonrpc._tcp

Boxee API Methods

The Boxee JSON api is split up into namespaces, which contain methods that can be called. These namespaces are:

JSONRPC          A variety of standard JSONRPC calls
Device           Pair and un-pair devices
Player           Manages all available players
AudioPlayer      Audio playback control
VideoPlayer      Video playback control
Slideshow        Picture playback control
Files            Shares information
System           System Controls and Information
XBMC             Application controls
GUI              GUI controls
Input            Input controls

JSONRPC

JSONRPC.Introspect

Returns a list of all available method calls

PARAMETERS
getdescriptions    boolean    OPTIONAL: return list of method descriptions

JSONRPC.Version

Returns the version of this API (not JSONRPC version). An even number refers to a stable version while odd number is development.

JSONRPC.Permission

Returns a list of client permissions

JSONRPC.Ping

Returns pong!


Device

Device.PairChallenge

Initiates a pairing request by sending a challenge to Boxee. Boxee displays a dialog box with a PIN that the user should type on the device and send to Boxee with Device.PairResponse

PARAMETERS
deviceid           string     identifier for the device (h/w address, MAC address, serial number, etc)
applicationid      string     identifier for the caller application
label              string     name of the caller application (displayed in the Boxee user interface)
icon               string     URL for the called application thumbnail (displayed in the Boxee user interface)
type               string     One of the following values: "tablet", "phone", "remote", "other

Device.PairResponse

In response to Device.PairChallenge, Boxee displays a dialog box with a PIN that the user should type on the device and send to Boxee using this method.

PARAMETERS
deviceid           string     identifier for the device (h/w address, MAC address, serial number, etc)
code               string     code entered by the user on the client device

Device.Unpair

Unpair a paired device.

PARAMETERS
deviceid           string     identifier for the device (h/w address, MAC address, serial number, etc)

Device.Connect

The client should call this method when (after pairing once) to authenticate itself with Boxee. If the device is paired, the client can continue and make additional calls to Boxee.

PARAMETERS
deviceid           string     identifier for the device (h/w address, MAC address, serial number, etc)

Player

Player.GetActivePlayers

Returns which players are active (available for querying)
Note: AudioPlayer, VideoPlayer and Slideshow methods are only available if there respective player is active, use this function to obtain that information

RESULT
video              boolean    True if video is available, false otherwise
audio              boolean    True if audio is available, false otherwise
picture            boolean    True if pictures are playing, false otherwise
browser            boolean    True if the web browser is running, false otherwise

AudioPlayer

AudioPlayer.State

Gets the state of the audio player

RESULT
playing            boolean    True if audio is currently playing
paused             boolean    True if audio is currently paused
stream             string     The URL or file name of stream
label              string     The name of the stream
seekable           string     True if it is possible to seek within this stream
can-play-next      string     True if it is possible to skip to a next file
can-play-prev      string     True if it is possible to skip to a previous file

AudioPlayer.PlayPause

Pauses or unpauses playback, returns new state

RESULT
playing            boolean    True if audio is currently playing
paused             boolean    True if audio is currently paused

AudioPlayer.Stop

Stops playback

AudioPlayer.SkipPrevious

Skips to the previous item in the playlist

AudioPlayer.SkipNext

Skips to the next item in the playlist

AudioPlayer.BigSkipBackward

Skips backward in the current track by a big amount

AudioPlayer.BigSkipForward

Skips forward in the current track by a big amount

AudioPlayer.SmallSkipBackward

Skips backward in the current track by a small amount

AudioPlayer.SmallSkipForward

Skips forward in the current track by a small amount

AudioPlayer.GetTime

Gets the state of the audio player, including time information

RESULT
time               object     Position in current track (hours, minutes, seconds, milliseconds)
total              object     Duration of current track (hours, minutes, seconds, milliseconds)
playing            boolean    True if audio is currently playing
paused             boolean    True if audio is currently paused

AudioPlayer.GetPercentage

Gets a percentage, of what is not obviously documented, presumably Position/Duration*100

RESULT             number     Percentage

AudioPlayer.SeekTime

Seek to a position in the track defined by position in seconds

PARAMETER          value     Position to seek to

AudioPlayer.SeekPercentage

Seek to a position in the track defined by a percentage (of total duration)

PARAMETER          value     Percentage to seek to

VideoPlayer

VideoPlayer contains exactly the same methods as AudioPlayer, see method in that namespace.

PicturePlayer

PicturePlayer.PlayPause

Pauses or unpauses slideshow.

PicturePlayer.Stop

Stops playback.

PicturePlayer.SkipPrevious

Skips to the previous item in the slideshow.

PicturePlayer.SkipNext

Skips to the next item in the slideshow.

PicturePlayer.MoveLeft

In a zoomed view, pans the viewport to the left.

PicturePlayer.MoveRight

In a zoomed view, pans the viewport to the right.

PicturePlayer.MoveDown

In a zoomed view, pans the viewport downwards.

PicturePlayer.MoveUp

In a zoomed view, pans the viewport upwards.

PicturePlayer.ZoomOut

Zooms the viewport out.

PicturePlayer.ZoomIn

Zooms the viewport in.

PicturePlayer.Zoom

Zoom to a defined level

PARAMETER          number     Zoom level to seek to, as a whole number between 1-10

PicturePlayer.Rotate

Rotate the current picture (clockwise or anticlockwise?)

Files

Many functions in this namespace allow filtering by type, valid types are the following:

video
music
pictures
files

Files.GetSources

Returns a list of available source directories (directories in root folder)

PARAMETER
media              string     media type filter, see Files namespace documentation for details
RESULT
shares             array      a list of file items in the directory
start              number
total              number
end                number

Files.GetDirectory

Returns a list of items in a directory, items can be filtered by type.

PARAMETER
directory          string     the directory to list, e.g. foo/bar
media              string     media type filter, see Files namespace documentation for details
RESULT
directories        array      sub-directories in this directory
files              array      files in this directory
limits            array      contains the following:
  start              number
  total              number
  end                number

System

System.Shutdown

Shuts down the system

System.Suspend

Suspends the system

System.Hibernate

Hibernates the system

System.Reboot

Reboots the system

System.GetInfoLabels

Get info labels about the system

PARAMETER         
labels              array      of string     <field name>s to return information for
RESULT            
array of object field name boolean value of that field   

System.GetInfoBooleans

Get info booleans about the system Available field names: system.canshutdown system.canpowerdown system.cansuspend system.canhibernate system.canreboot

PARAMETER         
booleans         array      of string     field names to return information for
RESULT           
array      of object field name boolean value of that field   

Example parameters:
{ "booleans": [ "system.canshutdown", "system.cansuspend" ] }

Example result:
[ { 'system.canshutdown' : true }, { 'system.cansuspend' : true }]

XBMC

XBMC.GetVolume

Gets the current volume

RESULT            number    volume  

XBMC.SetVolume

Sets the current volume as an int percent

PARAMETER         
value             number volume to set to

XBMC.ToggleMute

Toggle volume mute on/off, returns same as XBMC.GetVolume

XBMC.Play

Starts playback of a file / URL

PARAMETER         
file             string File name or URL to play
contenttype string Content type (i.e. video/mp4 or text/html) (optional)

XBMC.StartSlideshow

Starts slideshow

PARAMETER
directory        string     directory to show pictures from
random           boolean    True if show in random order (optional, default is True)
recursive        boolean    True if include pictures from subdirectories  (optional, default is True)

XBMC.Quit

Exits XBMC

GUI

GUI.TextFieldSet

If a text field / edit control is currently focused in the Boxee user interface, set it's value. It allows to use a "remote" keyboard to enter text.

PARAMETER
text             string     string text to set

GUI.KeyboardState

Returns the state of the on-screen virtual keyboard or it a text field / edit control is currently focused in the Boxee user interface.

RESULT
displayed        boolean    True if the on-screen virtual keyboard or it a text field / edit control is currently focused in the Boxee user interface
text             string     Value that's currently in the text field (if "displayed" is True)
password         boolean    True if the text field is a password field

GUI.NotificationShow

Show notification dialog for 5 seconds.

PARAMETER
msg             string     message to display in the notification dialog

Input

Input.NavigationState

Returns the current navigation state, whether a mouse or keys navigation is enabled.

RESULT
keys-enabled     boolean    True if the navigation keys are enabled (currently always True)
mouse-enabled    boolean    True if the mouse is  enabled

Input.Up

Sends a remote key up event

Input.Down

Sends a remote key down event

Input.Left

Sends a remote key left event

Input.Right

Sends a remote key right event

Input.Back

Sends a remote key back event

Input.Home

Return boxee to the home window

Input.MouseMovement

Sends a mouse movement event

PARAMETER
deltax            number      Delta on the X axis
deltay            number      Delta on the Y axis

Input.MouseClick

Sends a mouse click event

Boxee API Notifications

Category Notification Description
GUI KeyboardDisplay An on-screen keyboard is displayed or text field is focused
GUI KeyboardHide An on-screen keyboard is hidden or text field is unfocused
System Shutdown Boxee is being shutdown
System Suspend Boxee is being suspended
System Hibernate Boxee is being hibernated
System Reboot Boxee is being rebooted
System ApplicationStop Boxee is being stopped for some reason
Playback PlaybackStarted Playback of media has started
Playback PlaybackEnded Playback of media has ended
Playback PlaybackPaused Playback of media has paused
Playback PlaybackReumsed Playback of media has resumed after a pause
Playback PlaybackSeek Playback of media has seeked to another time
Playback PlaybackStopped Playback of media has stopped
Playback QueueNextItem Playback of the next media item in a playlist

Debugging

Direct interaction

To be able to test some methods of XBMC's JSON RPC API it can be of great help to be able to send a single hand-written JSON RPC request to XBMC to see its effect and the generated response. Depending on the transport protocol used there are different possibilities to do that:

TCP

With a telnet connection (using PuTTY on Windows or telnet on Linux) to port 9090 of the machine running XBMC it is possible to send and receive raw json data to/from XBMC.

Compatibility

Boxee 1.1

Supported features of JSON RPC 2.0

Unsupported features of JSON RPC 2.0


Third Party Tools

Boxee is not responsible for, or maintaining, any of the tools below.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox