WiC64meX, the WiC64-Media-Extension Developer Documentation

Prerequirements

You'll need a playlist and your media-files accessible on a webserver served via https(!).

These media-files can be anything that your user's browser can handle.

A playlist is a JSON file, containing an array at the top most level, each entry is an object.

You can have up to 65535 entries in your playlist. that's 2^16 - 1, more on that in section stop.

These object's have a mandatory url property, which is the full URL to the media-file.

And may have these optional properties:

wicmex_Gun          = $0000
wicmex_gun2         = $0001
wicmex_technoloop   = $0100
wicmex_technoloop_2 = $0101
wicmex_technoloop_3 = $0102

This is what an example playlist could look like:

[
    {
        "url": "https://wsmplaylists.shnbk.de/gun1.mp3",
        "rewindOnPlay": true,
        "name": "Gun"
    },
    {
        "url": "https://wsmplaylists.shnbk.de/gun2.mp3",
        "preload": true
    },
    {
        "url": "https://wsmplaylists.shnbk.de/technoloop.mp3",
        "loop": true,
        "skipTo": 256
    },
    {
        "url": "https://wsmplaylists.shnbk.de/technoloop.mp3",
        "loop": true,
        "rewindOnPlay": true
    },
    {
        "url": "https://wsmplaylists.shnbk.de/technoloop.mp3",
        "loop": true,
        "rewindOnPlay": true,
        "volume": 0.5
    }
]

this playlist ist availiable at https://wsmplaylists.shnbk.de/pl.json so you can try it out.

There is a playlist-checker available, that can validate your playlist and media-files.

There is also a playlist-editor available if you don't feel like writing JSON by hand.

workflow / api call from the WiC64

Every api-call gets you at least a single-byte response code, it's always the first byte of the response.

These codes are used:

register

At first, the C64 needs to register a session.

You do that by calling /r/<absolute-url-to-the-playlist-file.json but without https://>

Example: your playlist lives at https://example.com/sound/playlist-awesome.json

Then the C64 needs to call /r/example.com/sound/playlist-awesome.json

You'll always get back a 0x00 (OK) status followed by 8 bytes, they are printable ASCII characters, they are your session-id.

The first 4 are doubling as your user's join-code.

you might want to prompt your user to either:

WARNING

A Sessions is valid for 12 hours after the last activity. After that the Session will be deleted and all api-calls and website visits will fail as invalid session. What resets the Session Timeout:

what you can do as a developer to ensure a session lives at least as long as your program runs: periodically call the connection check api, see "connection check" below.

swaping Playlists

If you want to swap the playlist of an existing session, just call /P/<your-session-id>/<absolute-url-to-the-playlist-file.json but without https:// as in /r/>

You'll get back:

connection check

You may or may not, at any given time, want to know if a browser is connected to your session.

calling /c/<your-session-id> will return:

Depending on your use case this is either totally fine or a deal breaker, do with that what you want.

Media Control

All Media Control calls are basically the same, expect the initial command character.

All Media Controls uses the song-index, that is a hex representation of the array-index of the song in your playlist (first sound is 00, second is 01, 9th is 08, 10th is 09, 11th is 0A, 12th is 0B).

If you give a 2 byte song-index, bite-order is little-endian, so the first byte is the least significant byte.

That makes the second sound 0100, the 256th sound FF00 and the 257th sound 0001.

play

calling /p/<your-session-id>/<song-index> will play the song at the given index in your playlist, considering loop and rewindOnPlay properties. You'll get back:

pause

calling /h/<your-session-id>/<song-index> will pause the song at the given index in your playlist. You'll get back:

unpause

calling /u/<your-session-id>/<song-index> will unpause the song at the given index in your playlist, unpause meaning: is acts like play, but only if the sound is paused, otherwise it does nothing. You'll get back:

stop

calling /s/<your-session-id>/<song-index> will stop (and rewind) the song at the given index in your playlist. You'll get back:

stop all

stopall is a bit , it's just /a/<yoursession-id>, but feel free to call it with any song-index you like, it will be ignored.

as implied, it stops all playing sounds. You'll get back:

Showing the user a qr-code instead or in addition to the url

using sprites

if you like you can call /q/<your-session-id> to get a qrcode that you can show the user so they doesn't have to type in the join-url You'll get back:

1 2
3 4

The sprite is the foreground color, the background is transparent. this should be displayed on a dark background with a bright color, ideally a white sprite on a black background.

using plain petscii

if you like you can call /Q/<your-session-id> which gives you 1001 bytes, the first is:

followed by 1000 bytes, that is a 40x25 petscii representation of the qrcode. make that bright text on a dark background, ideally white on black. Also set the border color to the same as the background color.

It's either just spaces and inverted spaces, if the qrcode can be 25x25 or smaller, or