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:
- GET requests are used for status or data retrieval
- POST requests are used for all commands that might change status
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>]]]
- host: identifies the machine running OpenSong, for example localhost
- port: specifies the port on which OpenSong is listening for requests, by default 8080
- resource: mandatory part of the request to select a resource that will handle actions if applicable
- action: an optional string specifying the action to be executed
- identifier: an optional value to select a specific item. The meaning and allowed type is dependent on the resource and action
- param1...paramN: an optional parameter name. If parameters apply is action specific. Order of parameters is not relevant.
- value1...valueN: an optional parameter value for param. Valid parameter values are action specific
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:presentation_order] | 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. |
WebSocket
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. |