Jamdac chiptune files

If you compose music for the Jamdac synthesizer, you can distribute it 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 songs 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 song. 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 playing. (It might be possible to detect the 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. The development environment's 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.

   Sample file: example-chiptune.jamdac

3. Click the "Play" button to start playing a song.

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 songs, optional fields, and string lengths. The table below shows a possible layout for a file with two songs and every optional field.

Offset	Name	Example bytes	Value
0000	magic	4a 41 4d 44 41 43	"JAMDAC"
0006	format_version	01	1
0007	program_kind	00	0
0008	load_address	00 c0 00 00	$00c0_0000
000c	music_program_offset	04 2a	$042a
000e	work_block_size	10	16,384
000f	song_count	02	2
0010	song_length #0	01 2d	301
0012	song_length #1	8c a0	36,000
0014*	release_year	07 e9	2,025
0016*	album_title	04 44 45 4d 4f	"DEMO"
001b*	artist_name	04 44 45 4d 4f	"DEMO"
0020*	song_title #0	04 44 45 4d 4f	"DEMO"
0025*	song_title #1	04 44 45 4d 4f	"DEMO"
002a*	album_bitmap	. . .
042a	music_program	. . .

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

Important points:

• format_version must be 1; it supports future enhancements to the file format.
• program_kind must be 0; new kinds may be added in the future to indicate for example that the music program can coexist with another program, requires extra hardware features, or adheres to certain restrictions.
• load_address determines the memory address for the music_program bytes, whose length is determined by the end of file. The bytes must map to a valid memory range ($c0_0000 – $cf_ffff, or $10_0000 – $13_ffff).
• 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 permitted music program offset is $0012—just 18 bytes of overhead!
• The work block is the designated RAM area for use by the music program. It can be smaller than 256K, for example as a constraint for programming contests, or in the future to support a chiptune that coexists with other programs.
• The work_block_size specifies the size in multiples of 1,024 bytes. The special value $ff requests the entire RAM region (256K). The special value $00 requests the kernel scratchpad (64 bytes of memory at $d0_0080 in the I/O region), which means the load_address must be in the ROM region.
• If the kernel scratchpad is not requested, then the work block always starts in the RAM region at address $10_0000.
• The player must fill the work block with zero bytes before loading or writing bytes into it.
• If an album has multiple songs, they are all generated by the same music program. Valid song_count values are from 1 to 32.
• To play a song, the player writes the desired song_index (which must be less than song_count) as the first byte of the work block, then jumps to the load_address.
• If the load_address is in the RAM region instead of ROM, then the music program must be within the work block, and must not start at $10_0000 (overwritten by song_index).
• A fault may occur if the music program attempts to access RAM or ROM addresses outside the work block or loaded range.
• Some players may have less than 256k of RAM or no ROM region, and may reject files with certain load_address and work_block_size choices.
• The song_length units are increments of 100 ms = 2,205 samples, therefore the maximum length is just under two hours (1:49:13.5).
• 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 should access the Jamdac device only; a player is not required to provide any other IO module devices (video system, clock timer, etc.). A memory fault may occur if the program attempts to write to io locations for an absent device.
• The music player's virtual machine may be missing the 32-bit Floating Point Unit add-on, therefore the music program must not use floating point instructions.

MIME type

For HTTP and other content-typed transports, Jamdac chiptune files should be identified using the following media type:

• Media type: audio/x-jamdac
• File extension: .jamdac
• Magic number: 4a 41 4d 44 41 43 ("JAMDAC")

This media type is defined by the Jamdac file format specification and is the recommended Content-Type for serving .jamdac files.