RESTful web-services in JSIDPlay2
The emulator can be started in server mode and gives access to various functionalities like real-time streaming of SIDs or audio recognition and more. You can implement your own client to access this emulator. The server mode of JSIDPlay2 is called "JSIDPlay2Server"
The service methods are available running the server as a command-line tool explained in Server Setup or as an alternative by clicking start in JSIDPlay2 user interface version.
Preparation
General
All the following RESTful service methods of JSIDPlay2Server are using your configured music collections HVSC and CGSC.
To make the following examples work, first configure HVSC and CGSC music collection in JSIDPlay2, properly!
If you can browse these music collections in JSIDPlay2, the service methods can browse and stream the contained tune files as well.
Security
Basic authentication is used calling the services with the following pre-configured credentials:
-
Username: jsidplay2
-
Password: jsidplay2!
You can change the password of the user or add an administrative user
by an external configuration file tomcat-users.xml.
See Security Setup for more details.
Example Clients for JSIDPlay2Server
You can use my browser-enabled clients using the RESTful web-service API like C64 Jukebox or C64 Jukebox (TEAVM)
Or as an alternative, the source code of the example Android app interface can be found here. Click here to get the Installer for JSIDPlay2 App.
Please note: Streaming music using your mobile can cause additional costs!
JSIDPlay2Server – RESTful service endpoints
Info: Depending on the connection type of JSIDPlay2Server you have to use HTTP or HTTPS as protocol and port 8080 (HTTP) or 8443 (HTTPS). Please refer to the command-line parameters appServerConnectors, appServerPort and appServerSecurePort!
Stream e.g., SID as MP3 audio stream
Return an mp3 stream of the specified tune. On the server side, the emulator is started and streams the sound output back to the client. All parameters are used to specify emulation settings that should be used. Especially the MP3 parameters control the quality and size of the returned mp3 stream (vbr, cbr and vbrQuality). Using these parameters gives you the control about mobile phone transfer data volume and especially the costs that arise if you stream over the internet using your specific mobile phone provider contract (as nobody has an unlimited flat rate these days). It is recommended to use less data volume with less precision (lower quality) for connections over the internet and higher data volume with more precision (higher quality) inside your private local network, e.g., WLAN connection.
I have implemented an example android app as a client for JSIDPlay2Server. My android app uses constant bitrate of 64K for the internet and variable bitrate and the highest quality for my private WLAN. This is according to my recommendation above.
Example:
Stream e.g., D64 as RTMP video stream
Return a live stream of the specified demo. On the server side, the emulator is started and streams the video output back to the client. All parameters are used to specify emulation settings that should be used.
Note: I will not take responsibility for any costs that arise from streaming sound or video files from the internet!
Info: All Parameter names match exactly the command line parameter names of the console player in gnu style (prepended by --). For example, defaultLength=180 sets the default song length.
Info: The audio parameter lets you choose AVI as an alternative, but beware of a much bigger file size.
Example:
Get a number of log messages
Get a number of log messages of JSIDPlay2Server filtered by the given parameters.
Example:
Get directory contents containing music collections
You can access any subdirectory of your music collection to navigate to the tunes you want to play on the client side. HVSC music collection root path starts with "/C64Music/" and CGSC music collection starts with "/CGSC/". Please append any subdirectory behind that root path to get the desired directory contents. A slash appends directory type entries, whereas file type entries like tunes end with their file extensions. To each directory contents a parent folder entry will be added appended by "../". Following that directory entry, you can navigate back to the parent directory. Additionally, you can specify a file extension filter using the parameter filter, e.g., ".*\\.(sid|dat|mus|str|p00|prg|d64|mp3|mp4)$"
You can add more collections by creating an external configuration file located in your home directory.
The file must be named: "directoryServlet.properties" and be readable on startup of the server.
Example:
/MP3=/media/nas1/mp3,true (1)
/Assembly64=/media/nas1/Ken/C64/C64 Assembly64,false-
Syntax is: "<localDirectoryNameInTheRequest>" = "<realDirectoryName>", "<adminRoleRequired>"
In the request above use the URL "/jsidplay2service/JSIDPlay2REST/directory/MP3" or "/jsidplay2service/JSIDPlay2REST/directory/Assembly64" to access your collections.
Note: an Admin role can restrict access to collections to users with an admin role.
Example:
Get Directory of Disk
Return a list of directory entries of a C64 disk as PETSCII characters.
Example:
Get contents of a favorite tab
Return favorite tune files.
Note: The favorite names endpoint can be used to know how many favorites exist. And the favorite endpoint will fetch these. If this is called without a parameter, just the first favorites are fetched.
Example:
Get SID filter definitions
Note: SID filter names are prefixed with the emulation (RESID or RESIDFP) and the SID model (MOS6581 or MOS8580) and appended by their name, e.g., RESID_MOS8580_FilterAverage8580, That way filters can be grouped or sorted on the client side.
Example:
Get log message list
Return a list of JSIDPlay2Server’s logged messages filtered by the given parameters.
Example:
Get SID tune information list (STIL)
Return a list of information of the specified tune file.
Example:
Get SID tune’s current song length
Get song length (from the song length database) of a tune contained in your HVSC music collection.
Example:
SpeechToText recognition
SpeechToText recognition. Upload s16le samples continuously and get back a text result.
Example:
Get VUE demo pages or web resources
Load VUE demo pages or web resources into your web client.
Example:
Upload any C64 content to play it back
Upload C64 content to JSIDPlay2Server, to play back in the next step using the returned server path.
Example:
Keep alive video stream
Ping JSIDPlay2Server periodically, showing that the video is still watched.
Example:
This serves as a kind of proxy
This serves as a kind of proxy to make internal HTTP requests of HLS protocol through HTTPS to avoid mixed content in the browser.
Example:
Insert the next cart for the emulator running as a RTMP live video stream
Insert the next cart for a Player running as a RTMP live video stream.
Example:
Insert the next disk for the emulator running as a RTMP live video stream
Insert the next disk for the emulator running as a RTMP live video stream.
Example:
Press joystick 1/2 for the emulator running as a RTMP live video stream
Press joystick 1/2 for the emulator running as a RTMP live video stream.
Example:
Stop play video stream. Implements RTMP directive on_play_done configured in nginx.conf
Stop play video stream. Implements RTMP directive on_play_done configured in nginx.conf.
Example:
Play video stream. Implements RTMP directive on_play configured in nginx.conf
Play video stream. Implements RTMP directive on_play configured in nginx.conf.
Example:
Press the key for the emulator running as a RTMP live video stream
Press the key for the emulator running as a RTMP live video stream.
Example:
Set default emulation to RESIDFP for the emulator running as a RTMP live video stream
Set the default emulation to RESIDFP for the emulator running as a RTMP live video stream.
Example:
Set default emulation to RESID for emulator running as a RTMP live video stream
Set the default emulation to RESID for the emulator running as a RTMP live video stream.
Example:
Set the default chip model to MOS6581 for the emulator running as a RTMP live video stream
Set the default chip model to MOS6581 for the emulator running as a RTMP live video stream.
Example:
Set the default chip model to MOS8580 for the emulator running as a RTMP live video stream
Set the default chip model to MOS8580 for the emulator running as a RTMP live video stream.
Example:
Get ExSID(+) SID hardware mapping information
Get ExSID(+) SID mapping information. It contains which device to be used for a specific SID base address.
Example:
Get HardSID 4U, HardSID UPlay and HardSID Uno SID mapping information
Get HardSID 4U, HardSID UPlay and HardSID Uno SID mapping information. It contains which device to be used for a specific SID base address.
Example:
Get SIDBlaster SID mapping information
Get SIDBlaster SID mapping information. It contains which device to be used for a specific SID base address.
Example:
Get USBSID-Pico SID mapping information
Get USBSID-Pico SID mapping information. It contains which device to be used for a specific SID base address.
Example:
Upload WAV for tune recognition
Info: This service method does only work if the server has been started with additional WhatsSID database parameters.
This is a request to upload a WAV recording (a short audio recording max. 20 seconds should be enough).
The WAV file must meet the following requirement:
-
Sample size must be 16 bits
-
encoding must be signed (one short per sample -32768 … 32767)
-
the expected endianess is little endian
You are flexible to send:
-
mono or stereo
-
sampling frequencies 8KHz, 44.1KHz, 48KHz or 96KHz (but please use 8KHz to reduce the size of the request)
The resulting MusicInfo consists of HVSC entries title, author and release mapped to title, artist and album fields. InfoDir is the path within the HVSC.
Note: The confidence level in the response gives you an idea of how certain the tune has been identified. The bigger, the better.
Example: