Web server

The images shown below compare a song displayed in OpenSongApp and the same song shown in a web browser.  You can also see what the simplified navigation looks like.  When viewing a song from the song or set menu, < and > buttons allow you to navigate the songs in that menu.

From v6.1.3 you also have the option of showing or hiding the chords on devices when navigation is enabled.

Please note that the web version of the song does not include OpenSongApp features such as autoscroll and will only display OpenSong formatted songs.

The host's song option allows the client to automatically follow the songs displayed on the host's screen.  Songs will change automatically

If the network connection does not have internet access, users may not see the same fonts as on your device (as these require internet access to download once from https://fonts.google.com).  In this instance, they will use default fallback fonts.  Clients can always make sure they have these fonts already on their device 

Web server OpenSong API (added in v6.7.9)

If OpenSongApp is running a web server, it also exposes a built in API feature.  This allows web applications to get information from the hosting Android device, or tell the Android device to load a specific song.

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

The following features are currently available:

• http://[ip:port]/api/list : This will return a json file 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.

• http://[ip:port]/api/song : This will return a json object that describes the currently loaded song.  This 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).

• http://[ip:port]/api/song?folder=[FOLDER]&filename=[FILENAME] : This will return a json object for a specific song on the host Android device.  Note that this will only work if the host has enabled manual navigation on the web server.  If the song doesn't exist, the device's currently loaded song is returned instead .  This object 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).

• http://[ip:port]/api/remote?folder=[FOLDER]&filename=[FILENAME] : This will trigger the host running OpenSongApp to load a specific 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. 

• http://[ip:port]/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" to identify the song save location.  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);

   }

}