Web server API (v6.8.0+)

Found under: Settings > Web server

If OpenSongApp is running a web server, it also exposes a built in API feature. This allows web applications such as SongEditorWeb to access OpenSongApp data from the hosting Android device (currently songs), or tell the Android device to load a specific song.

To allow an Android device running OpenSongApp to deal with API request, it must

Be running the Web server feature
Have the "Listen for WebServer API calls" feature switched on on the Web server page.

The API needs to be called on the web server IP address and port that OpenSongApp is running e.g. http://[IP address]:[port]/api/[Feature]. e.g. http://192.168.0.2:8080/api/list

Please note the the web server runs over http. If you try to communicate via https, you may encounter problems and may need to set up a https -> http proxy.

Get a list of songs from the OpenSongApp device: /api/list

This will return a JSON text response with an array of songs available. Each song in the json array will have the following keys: filename, folder, title, uuid, lastModified. These are all string key:value pairs. You could, for example use this to build a song menu on your web application.

Get the song currently on the host device: /api/song

This will return a JSON song object that describes the currently loaded song. This JSON object also contains all of the normal song xml content again listed as key:value pairs. You could use this to display a song. Make sure you don't already have this song loaded (perhaps comparing the uuid or the folder/filename).

If you send this request and post a JSON file with the keys "folder" and "filename" matching a song retrieved from the list and the host device has enabled manual navigation, you will be returned a JSON object for that specific song, otherwise you will receive the current song as above.

This api method can also be called using suitable encrypted folder and filename GET methods (e.g. /api/song?folder=MAIN&filename=Love+Everlasting)

Tell the host to show a specific song: /api/remote

Sending a JSON with the keys:value pairs for "filename" and "folder" will instruct the gost device to load that secific song if they have enabled the listen to API commands feature in the webserver. If the song does not exist, the app will do nothing. It would be sensible to run the /api/list feature first to only send valid song folder/filenames. This will return a status 'ok' message if it worked.

This api method can also be called using suitable encrypted folder and filename GET methods (e.g. /api/remote?folder=MAIN&filename=Love+Everlasting)

Tell the host to save a specific song: /api/save

This will trigger the host running OpenSongApp to save the edited song sent as a JSON object via a POST request. The JSON object for a song must contain the appropriate xml values as key:value pairs and must also contain the required "folder" and "filename" keys to identify the song save location. It must also contain valid "lastModified" and "uuid" keys. The "uuid" key must be preserved when editing songs and freshly generated for new songs.

Please check the sample song JSON object structure.

Sets cannot yet be sent to OpenSongApp using this method.

You can see an example of a song object or song list object json file that would be returned using the above methods below:

In order to listen via WebSockets for song changes on the Android device, you will need to implement a websocket listener as follows (Javascript):

// Make sure you have a way to get and store the OpenSongApp ipaddress and port numbers

// var ipaddress;

// var port;

socket = new WebSocket('ws://' + ipaddress + ':' + port + '/updates');

socket.onmessage = function(event) {

try {

var payload = JSON.parse(event.data);

//Handle the Refresh/Song Change action

if (payload.action === 'REFRESH') {

updateSong();

}

} catch (e) {

if (event.data === 'REFRESH') {

updateSong();

}

async function updateSong() {

try {

const response = await fetch('http://' + ipaddress + ':' + port + '/api/song');

const songData = await response.json();

console.log("Now getting:", songData.title);

// Update PWA UI with songData fields

} catch (error) {

console.error("Connection to OpenSongApp failed", error);

}

Requirements

Device requirements:

Google Play Services (part of Google Play Store) for WiFi hotspot
WiFi equipped. The device does not need to be, but can be, connected to a network
Local WiFi hotspot requires Android 8 (and above)

Android Permissions required:

INTERNET, ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE (for Web server and WiFi hotspot)
Android 13 (and above): NEARBY_WIFI_DEVICES (for WiFi hotspot)

Android 11/12: ACCESS_FINE_LOCATION (for WiFi hotspot)
Android 10 or lower: ACCESS_COARSE_LOCATION (for WiFi hotspot)

Page updated

Google Sites

Report abuse