Jamdac chiptune files

If you compose songs for the Jamdac synthesizer, you can distribute your music using the .jamdac file format. It is specifically designed for use by an audio player app such as the Jamdac Jukebox from the Hybrix website.

Key features of the Jamdac chiptune file format:

• A single .jamdac file may contain multiple song tracks organized into an album.
• The file stores a Chombit program binary that plays music using the Jamdac device. It is inspired by the .sid file format from the Commodore 64 demoscene. Storing music as executable code is quite unusual. Most typical audio file formats store data instead—either waveform samples (for example .mp3 or .wav format) or else lists of notes (for example .mid or .mod format).
• As a result, a .jamdac file can be extremely compact, perhaps less than 10 kilobytes for an entire album of songs.
• The file header must include a precomputed time length for each track. This is important for an audio player app, which may need to display a list of songs and their lengths, as well as a progress bar while a song is playing. (It might be possible to detect the track length automatically by running the music program until it finishes; however, that approach would be computationally wasteful.)
• The file format can optionally include an album title, year, and artist name.
• The file format can also optionally include an album image that is a 32 × 32 pixel bitmap. The music player should display it using the system palette, with transparent and theme colors shown as black.

Tip: The chiptune file format is for music only. To distribute a full program that has interactive video graphics, use a Hybrix ROM cartridge file instead.

Creating a Jamdac file

1. Create a Hybrix project with the songs you want to export.

2. If you want an album image, create a 32 × 32 sprite. In the current design, the exporter simply chooses the first image frame of the first sprite with 32 × 32 dimensions.

3. In your web browser, open the Hybrix development environment, go to the SONGS tab, and then click "EXPORT…". The .jamdac file will download to your computer.

Playing a Jamdac file

1. In your web browser, open the Hybrix development environment, go to the SONGS tab, and then click "JUKEBOX…" to launch the Jamdac Jukebox audio player app.

2. A pop-up window will appear. You can click "OPEN FILE…" or simply drag+drop your .jamdac file onto the window.

3. Click the "PLAY" button to start playing a track.

File format specification

It is possible for third-party tools to read or write .jamdac files. Unlike Hybrix ROM files, the .jamdac file format is relatively simple, without any data compression or integrity checks. The file header size depends on the number of song tracks, optional fields, and string lengths. The table below shows a possible layout for a file with two tracks and all optional fields.

Offset	Example bytes	Value	Description
0000	4A 41 4D 44 41 43	"JAMDAC"	File format magic number
0006	01	1	File format version (must be 1)
0007	01	1	Virtual machine type (must be 1)
0008	00 C0 00 00	$00C0_0000	Load address for music program
000C	04 2A	$042A	Music program offset in this file
000E	10	16,384	Requested RAM segment size divided by 1,024; or$FF requests the VM default (256K)
000F	02	2	Track count (between 1 and 32)
0010	01 2D	301	Track #0 length: 301 = 30.1 seconds
0012	8C A0	36,000	Track #1 length: 36,000 = 1 hour
0014	07 E9	2,025	Album release year*
0016	04 44 45 4D 4F	"DEMO"	Album title string*
001B	04 44 45 4D 4F	"DEMO"	Artist name string*
0020	04 44 45 4D 4F	"DEMO"	Track #0 title string*
0025	04 44 45 4D 4F	"DEMO"	Track #1 title string*
002A	. . .		32 × 32 album bitmap (1,024 bytes)*
042A	. . .		Start of music program bytes

*The starred fields are optional, but if one field is omitted then the subsequent fields must be omitted as well.

Important points:

• The music program offset indicates whether optional fields are present or not. To prevent mistakes, the offset must exactly equal the position of the first omitted field; otherwise the loader will report an error. The smallest legal music program offset is $0014—just 20 bytes of overhead!
• Track lengths are measured as increments of 100 ms = 2,205 samples, therefore the maximum track length is just under two hours (1:49:13.5)
• The requested RAM segment size (offset $000E) can be used to indicate compatibility with a reduced virtual machine, for example as used in programming contests. A value of $00 requests no RAM segment at all; the music program must rely entirely on kernel globals.
• Title/name characters are preceded by a byte indicating the string length, for example $04 before $44 $45 $4D $4F to encode "DEMO".
• The music program is loaded at the specified load address, which must be in the ROM segment ($00CX_XXXXX) or RAM segment ($001X_XXXX).
• The music program starts by jumping to the load address.
• If an album has multiple tracks, they are all generated by the same music program. The audio player app communicates the requested track index using IO::CPU_EVENT_VALUE ($D0_001C).
• The music player's virtual machine has the Jamdac device only; all the other IO module devices (video system, clock timer, etc.) will be absent. A memory fault will occur if the program attempts to write to IO locations for an absent device.
• The music player's virtual machine does not support the 32-bit Floating Point Unit add-on.