OpenSong API

An automation interface for OpenSong to provide access to the main functionality using a REST approach over HTTP and WebSocket. This API is available as of OpenSong 2.0 beta2.

Background

OpenSong is an application for managing and projecting songs, lyrics and chords, scripture fragments, free text, images and videos. OpenSong is cross platform, but the support is limited to the platforms made available by the IDE, which at present covers MacOS, Windows and Linux. There is an increased amount of requests to make OpenSong available on other platforms, such as iOS, Android or mobile platforms in general. This requires a complete rewrite in another platform specific language, or a different approach: an API. This API also facilitates automation or remote control for example from show control software.

Purpose

The OpenSong API provides access to the OpenSong core elements for information retrieval, or modifying status. This means that external applications can request for example status information, or control a presentation without requiring a port of the business logic of OpenSong onto a different platform.

An example of a method exposed by the OpenSong API is to retrieve the current status in XML form:

GET http://localhost:8082/presentation/status

The response generally is an XML document of the following form, for example in response to the request above:

<?xml version="1.0" encoding="UTF-8"?>
<response resource="presentation" action="status">
  <presentation running="1">
    <screen mode="N">normal</screen>
    <slide itemnumber="1">
      <name>Testslide</name>
      <title>Untitled</title>
     </slide>
   </presentation>
</response>

The value of the presentation attribute running is 1 or 0 depending on whether a presentation is running or not.

The child nodes of presentation are only available in case of an active presentation (attribute running = 1).

The slide attribute itemnumber is a unique identifier (numeric) of a slide in a set. This number is generated on launch of a presentation and will not change during a presentation. Dynamically inserted slides will also have a unique number. The itemnumber therefore is not always a sequence number indicating the position of the slide in the set.

Specification

All communication travels over HTTP, OpenSong itself is the server, by default running on port 8082. The API is a RESTful service. The commands are executed using GET and POST methods:

Replies generally consist of an XML document, with exception for specific actions, for example retrieving the current slide image, which will return a JPEG image.

An HTTP request has the following typical form:

http://host:port/resource[/action[/identifier][/param1:value1[/paramN:valueN]]]

Authentication

A basic level of authentication is used. Generally, authentication is required for all POST requests. Most GET requests do not require authentication. In case authentication is required, but no credentials are supplied, OpenSong will reply with an HTTP Basic Authentication request response. OpenSong does not facilitate configuring multiple users and passwords. The authentication is handled by a single authentication key that is to be supplied in the Basic Authentication request header:

Authorization: Basic __base64_encoded_key__

Resources

The following sections describe the available resources. Note that several URIs are split over multiple lines due to automatic line wrapping. All URIs need to be entered as one line, without line breaks, except for those explicitly separated by 'or' on separate lines.

presentation

Handling information in a running presentation.

This resources requires an action to be specified.

Method URI Implemented Response or consequence
GET /presentation/status yes The status of OpenSong, see the example response above.
GET /presentation/slide or /presentation/slide/list yes A list of the slides in the current presentation including slide generics (name, title, slide number).
GET /presentation/slide/identifier yes The raw XML data of a slide. Identifier is the slide item number as available in the XML provided by the action list.
GET /presentation/slide/identifier/preview[/width:x][/height:y][/quality:value] yes Preview image for slide in JPEG file format. The dimensions of the preview default to the size of the preview on the presentation helper window or 160x120 in case the presentation helper is not active. Optionally specify parameter width to set the width in pixels (max 4096) either or not in combination with parameter height to set the height in pixels (max 4096). Parameter quality optionally can be set to specify the quality of the JPEG preview, 0=lowest quality, 100=highest quality. Identifier is slide item number as available in the XML provided by the action list, or 'current'.
GET /presentation/slide/identifier/image[/width:x][/height:y][/quality:value] yes Image of slide in JPEG file format. The dimensions of the image default to the size of the present window, which equal the dimensions of the projector screen. Optionally specify parameter width to set the width in pixels (max 4096) either or not in combination with parameter height to set the height in pixels (max 4096). The parameters width and height are not of influence when using the identifier 'current' to retrieve the slide currently at presentation. Parameter quality optionally can be set to specify the quality of the JPEG preview, 0=lowest quality, 100=highest quality. Identifier is slide item number as available in the XML provided by the action list, or 'current'.
POST /presentation/slide/song[/folder:name]/song:name[/after:slide_number][/order:presentationorder] yes (as of release 2.2, rev. 917) Inserts a song to the current showing set. Parameter folder value is the name of the folder to load the songs from. Of absent, the song is in the song folder root. Parameter song is the name of the song to load. Parameter after is the slide number position after which the song is to be inserted. When 0, the song will be inserted as first item in the set. When absent, the song will be inserted after the current slide(group). Parameter order specifies the optional verses, chorus, bridge, .. elements from a song that are to be added (this is wat is referred to in the application as 'presentation order'). When absent, the default presentation order of the song will be used. It is allowed to specify more than once verse by using a comma separated list, e.g. 'V1,C,V2,B,V2,V3'
POST /presentation/slide/scripture/[tbd] Insert a new scripture (requires additional parameters, to be defined)
POST /presentation/slide/identifier yes Directly jump to a slide. Identifier is the slide item number as available in the XML provided by the action list.
POST /presentation/slide/next yes Move over to the next slide
POST /presentation/slide/previous yes Move over to the previous slide
POST /presentation/slide/first yes Jump to the first slide
POST /presentation/slide/last yes Jump to the last slide
POST /presentation/section/next yes Go to next section
POST /presentation/section/previous yes Go to previous section
POST /presentation/song/identifier yes Jump to a specific song within the set. Identifier is the song order number.
POST /presentation/song/current/chorus yes Jump to (first following) chorus within the current song (if applicable in the current song).
POST /presentation/song/current/bridge yes Jump to (first following) bridge within the current song (if applicable in the current song).
POST /presentation/song/current/prechorus yes Jump to (first following) pre-chorus within the current song (if applicable in the current song).
POST /presentation/song/current/tag yes Jump to (first following) tag within the current song (if applicable in the current song).
POST /presentation/song/current/verse/verse:number yes Jump to a specific verse within the current song (if applicable in the current song).
POST /presentation/screen/normal yes Switch (back) to normal screen display mode.
POST /presentation/screen/[toggle_]black yes Show black screen. If current screen is black screen, switch to normal screen.
POST /presentation/screen/[toggle_]white yes Show white screen. If current screen is white screen, switch to normal screen.
POST /presentation/screen/[toggle_]hide yes Show current background (hide text). If current screen mode is hide, switch to normal screen.
POST /presentation/screen/[toggle_]logo yes Show logo over current screen. If logo is displayed, switch to normal screen.
POST /presentation/screen/[toggle_]freeze yes Freeze current screen, do not update screen changes. If current screen mode is freeze screen, switch to normal screen.
POST /presentation/screen/alert/message:text yes Shows alert on screen. Parameter message, text value is the text message to be shown. When the parameter is absent or empty, the currently showing alert (if any) will be removed. You can use plain (ascii) text, or - as of as of release 2.2, rev. 918 - UTF-8.
POST /presentation/close yes End the current running presentation (without interactive user confirmation).

song

Exchanging song related data.

Method URI Implemented Response or consequence
GET /song or /song/list[/folder:name] yes A list of all songs in the root song directory, or the song in the folder specified by the parameter 'folder'.
GET /song/[detail]/identifier[/folder:name] yes The raw XML of a song.
GET /song/folders yes A list with the names of the available song folders.
POST /song/load/identifier[/folder:name] yes (2.0 final) Loads the song specified by the song name as identifier.
POST /song/present/identifier[/folder:name][/slide:index][/display:mode] yes (2.0 final) Starts a presentation using the song specified by the set name as identifier. Optionally a starting slide can be specified. Omission of the parameter has the same effect as using slide_index=1. The optional display parameter determines the display mode where 1 is single display and 2 is dual display (launching presentation helper). Dual display is default. Parameter slide and parameter display can be swapped and both are optional.

set

Exchanging set related data.

Method URI Implemented Response or consequence
GET /set or /set/list yes A list with the names of all available sets.
GET /set/slide/identifier yes A list of slides in the set specified by the set name as identifier. A short summary per slide will be returned. For full slide details, specify a slide by index, see next.
GET /set/slide/identifier/slide:index yes The full (raw) slide contents from the set specified by the set name as identifier and the slide index as parameter.
POST /set/load/identifier yes (2.0 final) Loads the set specified by the set name as identifier.
POST /set/present/identifier[/slide:index][/display:mode] yes (2.0 final) Starts a presentation using the set specified by the set name as identifier. Optionally a starting slide can be specified. Omission of the parameter has the same effect as using slide_index=1. The optional display parameter determines the display mode where 1 is single display and 2 is dual display (launching presentation helper). Dual display is default. Parameter slide and parameter display can be swapped and both are optional.

ws

This resource provides access to the websocket interface. Using websockets enables bidirectional communication and status pushing from OpenSong to the client instead of polling using the actions listed above.

To initiate a websocket session, connect the client to

ws://host:port/ws

The socket interface provides full interactive access to all resources by sending the regular URI request as text data to OpenSong:

resource[/action[/identifier][/param1:value1[/paramN:valueN]]]

The websocket implementation is basic and limited to sending complete data frames for text or binary data using the approved WebSocket specification RFC 6455. At present the implemented functionality is fully backwards compatible to draft hybi-10. Secure websockets (wss) are not supported.

The websocket connection is not authenticated, therefore actions that modify the state of OpenSong, such as loading a set or changing a slide are not allowed. This means that the ws resource allows all GET actions, plus the ws resource actions:

URI Implemented Activity
/ws/subscribe/identifier yes Activates notifications for a specific topic, generally identical to a resource name. Supported: presentation
/ws/unsubscribe/identifier yes Deactivates notifications for a specific topic, genarally identical to a resource name.