Music Recorder/Jukebox Technical Documentation 0.1
March 30, 2022
Shonumi aka D.S. Baxter

***************************************************
1. Introduction
***************************************************

The Game Boy Advance Music Recorder is a cartridge for the Game Boy Advance capable of playing MP3s, recording audio, and performing karaoke. Designed and developed by Kemco, it was released on November 15, 2002 in Japan. A year later, Radica Games became the distributor for the product in North America and released it as the Game Boy Advance Jukebox. It marked the first time an officially licensed product could playback media of the user's choosing on the Game Boy.


***************************************************
2. General Hardware Information
***************************************************

- Comes in an oversized black or white cartridge that hangs over the backside of a Game Boy Advance.
- Comes with a red LED at the bottom to indicate activity.
- Comes with a built-in microphone along with a Line-In port.
- Requires 1 AA battery to operate.
- Requires a CompactFlash card to operate.
- Internally, PCB is split into two main sections connected together.
- Supports audio output through a headphone jack.
- Supports playing MP3 files, recording voice memos as WAV files, and recording music/karaoke as custom GB3 files.
- Capable of operating independently from the Game Boy Advance. Has physical buttons to control playback.


***************************************************
3. I/O Registers
*************************************************** 

All registers for the Music Recorder/Jukebox are 8-bit. They are located in the 0xB------ address range.

-----------------------------------------------------------
Address		| Register Name
-----------------------------------------------------------
0xB000000	| UNKNOWN
0xB020000	| UNKNOWN
0xB080000	| ZMP_INDEX_HI
0xB0A0000	| ZMP_INDEX_LO
0xB0C0000	| ZMP_DATA_HI
0xB0E0000	| ZMP_DATA_LO
0xB100000	| UNKNOWN
0xB120000	| ZMP_STATUS_RESET

ZMP_INDEX_HI and ZMP_INDEX_LO are used to set the current index. Each index points to specific data from the hardware, such as the current output volume, users settings, battery level, and the time remaining for recording or music playback. Each index is 16-bit and ZMP_INDEX_HI and ZMP_INDEX_LO form two 8-bits components of that value. ZMP_INDEX_HI contains the upper 8-bits and ZMP_INDEX_LO contains the lower 8-bits.

ZMP_DATA_HI and ZMP_DATA_LO are used to read data from or write data to the selected index. Data inside each index is also 16-bit, therefore ZMP_DATA_HI accesses the upper 8-bits and ZMP_DATA_LO accesses the lower 8-bits.

ZMP_STATUS_RESET forcibly resets the current value of cartridge's reported status. To do so, ZMP_STATUS_RESET must first be set to 0x00. After brief delay (approximately 16ms is sufficient) ZMP_STATUS_RESET must then be set to 0x01. The cartridge's status will then reset to zero after a period of about 500ms. The status is reported by the Device Status index. The upper-half of the index appears to represent the current audio playback state while lower half represent the current command issued to the cartridge.

Registers 0xB000000, 0xB020000, and 0xB100000 appear to be used by the software under certain circumstances, however, their purpose is currently unknown.


***************************************************
4. Command Overview
***************************************************

The major functions of the Music Recorder/Jukebox are controlled from the software by sending a series of commands. Complex tasks such as reading the CompactFlash memory card or even deciding when to decode MP3 files are largely abstracted away from the CPU by a simple, high-level interface. To issue a command, software must follow the proceedure listed below:

1) Write the value 0x0000 to the index 0x0081, then delay about 16ms.

2) Write the command to the index 0x0080.

3) Write the value 0x0000 to ZMP_STATUS_RESET, delay about 16ms, then write the value 0x0001 to ZMP_STATUS_RESET. 

After writing to ZMP_STATUS_RESET, the Device Status index will then return either 0x100 in most cases, or 0x8000 when performing certain audio operations.

Each command is 8-bits in length and occupy the lower half of the Device Status index. Their values serve as enumerations to various audio and memory related functions. The software has been observed using the below commands:

-----------------------------------------------------------
Command		| Description
-----------------------------------------------------------
0x00		| Unknown
0x01		| Unknown
0x02		| Format CompactFlash Card
0x08		| Select Music Files
0x09		| Record Music Files
0x0A		| Select Voice Memo Files
0x0B		| Record Voice Memo Files
0x0C		| Select Karaoke Files
0x0D		| Record Karaoke Files
0x0E		| Unknown
0x10		| Unknown
0x11		| Commit Title/Artist Changes
0x13		| Play Selected Audio File/Record New Audio File 	
0x14		| Reset Currently Selected Audio File
0x15		| Move Forward 1 Audio File
0x16		| Move Backward 1 Audio File
0x19		| Delete Current Audio File
0x20		| Stop Playing/Recording Audio File


***************************************************
5. Command Usage
***************************************************

For all commands dealing with audio input/output (0x109, 0x10B, 0x10D, 0x113), refer to the section below for dealing with the actual data transfers.

[[Command 0x00 - Unknown]]

This is the first command that the software for the Music Recorder/Jukebox issues. The software also sends this command after finishing recording Music Files, indicating that it might reset or initialize functions related to the Line-In jack.





[[Command 0x01 - Unknown]]

This is the second command that the software for the Music Recorder/Jukebox issues, indicating that it is possibly used to initialize the hardware.





[[Command 0x02 - Format CompactFlash Card]]

This command will format the CompactFlash card inserted into the Music Recorder/Jukebox. Presumably, it also creates several directories used to separate music files into different categories. It also creates the AGB.INFO file in the root directory, which contains a list of all MP3 files detected by the hardware.

Once this command has been sent, the index 0x101 is used to measure the progress of the formatting process. The 16-bit value in that index represent progress in 1 / 32768 units. That is to say, 0% is 0x0000, 25% is 0x2000, 50% is 0x4000, 75% is 0x6000, and 100% is 0x8000. Various percentages can be created using any value in between 0x0000 through 0x8000. For example, ~14.22% would be 0x1234.

The software only displays whole integers, ignoring any decimals results. Surprisingly, it can measure 0% through 199%.





[[Command 0x08 - Select Music Files]]

This command is used to read information about MP3 music files or any music recordings via Line-In stored on the CompactFlash card. It is also used to select the Music/Line-In Recordings category when playing files. The command largely affects the output of indices 0x00A1 - 0x00A6 and 0x00B0 - 0x00CF for data relating to the music's filename, formal title, and artist.





[[Command 0x09 - Record Music]]

This command prepares the Music Recorder/Jukebox to record audio data from the Line-In jack. After sending this command, the software waits for the CompactFlash Status index to change to the value 0x1010 to indicate the hardware is ready. Input data from the jack is then stored as a sequentially numbered .GB3 file. The user can optionally turn on a "Silence Detection" feature that splits incoming audio data into seperate files when a period of silence appears in the stream, automatically breaking up songs from CDs or cassette players for example.





[[Command 0x0A - Select Voice Memo Files]]

This command is used to read information about Voice Memo files recorded via the built-in microphone and stored on the CompactFlash card. It is also used to select the Voice Memo category when playing files. The command largely affects the output of indices 0x00A1 - 0x00A6 for data relating to the memo's filename.




[[Command 0x0B - Record Voice Memo Files]]

This command prepares the Music Recorder/Jukebox's to record audio data from the microphone. Input data from the microphone is then stored in sequentially numbered .WAV files.




[[Command 0x0C - Select Karaoke Files]]

This command is used to read information about Karaoke Files stored on the CompactFlash card and created by playing audio from the Music Files and recording over them with the microphone. The command largely affects the output of indices 0x00A1 - 0x00A6 for data relating to the memo's filename.




[[Command 0x0D - Record Karaoke Files]]

This command prepares the Music Recorder/Jukebox to record audio data from the microphone on top of the unit and by mixing audio samples from one of the Music Files. When recording Karaoke Files, the user is prompted to first select an existing Music File.





[[Command 0x0E - Unknown]]

This command always follows the 0x01 command. The Music Recorder/Jukebox's software appears to only issue this command at the very beginning when initializing hardware.





[[Command 0x10 - Unknown]]

This command always follows a command related to file access (0x08, 0x0A, 0x0C, 0x14, 0x15, 0x16, and 0x19), indicating that it might serve as a means to update the current list of files for a given category. For commands that select a given category (0x08, 0x0A, and 0x0C), the software for the Music Recorder/Jukebox issues this command twice in a row.





[[Command 0x11 - Commit Title/Artist Changes]]

For .GB3 files recorded via the Line-In jack, the Music Recorder/Jukebox software allows users to manually input the song's full name as well as the artist. Up to 30 characters can be used for either the title or artist fields. The software writes the data to the relevant indices at 0xB0 - 0xCF and sends this command to save the data.





[[Command 0x13 - Play Selected Audio File/Record New Audio File]]

This command either plays a selected audio file or starts recording a new file, depending on which commands were previously issued. All 3 categories of audio - Music, Voice Memo, and Karaoke - use this command to actually output audio. For recording, the commands 0x09, 0x0B, and 0x0D merely prep the hardware for recording a new file, while this command actually instructs the hardware to start grabbing input audio samples. Most importantly, this command affects the value of the CompactFlash Status index, depending on which category of audio has been selected and whether the mode is playing or recording:

-----------------------------------------------------------
Mode			| CompactFlash Status
-----------------------------------------------------------
Music Play		| 0x1001
Music Record		| 0x1012
Voice Memo Play 	| 0x1101
Voice Memo Record	| 0x1112
Karaoke Play		| 0x1201
Karaoke Record		| 0x1211
-----------------------------------------------------------

When the song is finished playing, or when there is no space left on the CompactFlash card, the CompactFlash Status index stops matching those above values.





[[Command 0x14 - Reset Currently Selected Audio File]]

This command appears to reset any information regarding the currently selected file. The Music Recorder/Jukebox issues this command on boot and again every time the user exits the "PLAY" or "REC" menus for a given category of audio.





[[Command 0x15 - Move Forward 1 Audio File]]

Select the next audio file for playback. If the current file is the last file for a given audio category, the audio file at the beginning of the list is selected instead.





[[Command 0x16 - Move Backward 1 Audio File]]

Selects the previous audio file for playback. If the current file is the first file for a given audio category, the audio file at the end of the list is selected instead.





[[Command 0x17 - Move Audio File 1 Slot Forward]]

This command changes the order of audio files when playing them from the Music category. It will take the currently selected song and move it up one slot, effectively allowing the user to make a customized playlist. For example, if the selected song is #1 in the playlist, this command will move it into slot #2. The previous song that was in slot #2 will also move to slot #1. If the selected song occupies the last slot in the playlist, the Music Recorder/Jukebox's interface prevents the user from executing this command.





[[Command 0x18 - Move Audio File 1 Slot Backward]]

This command changes the order of audio files when playing them from the Music category. It will take the currently selected song and move it down one slot, effectively allowing the user to make a customized playlist. For example, if the selected song is #2 in the playlist, this command will move it into slot #1. The previous song that was in slot #1 will also move to slot #2. If the selected song occupies the first slot in the playlist, the Music Recorder/Jukebox's interface prevents the user from executing this command.





[[Command 0x19 - Delete Current Audio File]]

Erases all data for the current audio file from the CompactFlash card.





[[Command 0x20 - Stop Playing/Recording Audio File]]

Halts all audio input/output for a given audio file.


***************************************************
6. Index Overview & Usage
***************************************************

Each index is mapped to different hardware data, giving the CPU access to information regarding music playback or recording. Below is a list of known indices and their roles:

-----------------------------------------------------------
Index	| R/W	| Description
-----------------------------------------------------------
0x0080	| W	| Write Device Status
0x0081	| R	| Read Device Status
0x0082	| R	| CompactFlash Status
0x0084	| R	| Remaining Playback Time (Minutes)
0x0085	| R	| Remaining Playback Time (Seconds)
0x0086	| R	| Remaining Recording Time (Minutes)
0x0087	| R	| Remaining Recording Time (Seconds)
0x0088	| R/W	| Music Output Volume (0x3F = Min, 0x00 = Max)
0x008A	| R/W	| Voice Output Volume (0x3F = Min, 0x00 = Max)
0x008C	| R/W	| Equalizer Settings
0x008B	| R	| Recording Volume (0xFFEE = Min, 0x0004 = Max)
0x008F	| R/W	| Voice Cancellation Settings
0x009A	| R/W	| Spectrum Analyzer Update Status
0x009B	| R/W	| GBA Speaker Volume db (0xFFEC = Min, 0x0013 = Max)
0x009C	| R	| CompactFlash Detection Flag
0x009D	| R	| Battery Level (Min = 0x02, Max = 0x00)
0x00A0	| R	| Current File Track Number
0x00AD	| R	| Current Number of Music Files Detected
0x00AE	| R	| Current Number of Voice Memo Files Detected
0x00AF	| R	| Current Number of Karaoke Files Detected
0x0100	| R	| Audio Index Length
0x0101	| R	| CompactFlash Format Progress / CompactFlash Access Progress???
0x0102	| R	| Current Karaoke File Number for Recording (Hundreds Value)
0x0103	| R	| Current Karaoke File Number for Recording (Tens and Ones Values)
0x01C8	| R/W	| General Configuration Settings
0x01C9	| R/W	| Line-In and Microphone Input Levels

Index 0x0080 - Write Device Status
Allows the CPU to overwrite the cartridge's 16-bit STATUS value. When STATUS is set to certain values, it acts as a command.

Index 0x0081 - Read Device Status
Returns the CPU to read the cartridge's 16-bit STATUS value. Primarily used to see if the cartridge is ready to perform certain operations after issuing a command.

Index 0x0082 - CompactFlash Status
Returns the current state of the CompactFlash card. When recording music, it should read 0x1010.

Index 0x0084 - Remaining Playback Time (Minutes)
Returns the remaining minutes left when playing a music file or recording. Has a range of 0 - 99. The cartridge's hardware will automatically update the value during playback.

Index 0x0085 - Remaining Playback Time (Seconds)
Returns the remaining seconds left when playing a music file or recording. Has a range of 0 - 59. The cartridge's hardware will automatically update the value during playback.

Index 0x0086 - Remaining Recording Time (Minutes)
Returns the remaining minutes left when making any recording. Has a range of 0 - 99. The value is dependent on remaining free space of the CompactFlash card and the audio quality chosen for recording. The cartridge's hardware will automatically update the value during a recording session.

Index 0x0087 - Remaining Recording Time (Seconds)
Returns the remaining seconds left when making any recording. Has a range of 0 - 59. The value is dependent on remaining free space of the CompactFlash card and the audio quality chosen for recording. The cartridge's hardware will automatically update the value during a recording session.

Index 0x0088 - Music Output Volume
Specifies the output volume for Music and Karaoke Files through either the GBA's speakers or the cartridge's built-in headphone jack. Has a range of 0x3F - 0x00, for minimum to maximum volume. Operates separately from the Voice Output Volume index.

Index 0x008A - Voice Output Volume
Specifies the output volume for Voice Memo Files through either the GBA's speakers or the cartridge's built-in headphone jack. Has a range of 0x3F - 0x00, minimum to maximum volume. Operates separately from the Music Output Volume index, however an apparent software glitch seems to overwrite this index with the other volume index when switching audio categories.

Index 0x008C - Equalizer Settings
Specifies the type of equalizer to apply for music playback. Accepts values of 0 - 4 to select the following equalizers respectively: None, Jazz, Pop, Classical, Rock.

Index 0x008B - Recording Volume
Returns the current volume of input audio from the a recording (via Line-In or the microphone).

Index 0x008F - Voice Cancellation Settings
Toggles voice cancellation during audio playback. 0 = OFF, 1 = ON.

Index 0x009A - Spectrum Analyzer Update Status
Represents when the spectrum analyzer for Music Files needs to be updated. When this value is zero, the spectrum analyzer is disabled. For any non-zero values, the spectrum analyzer is enabled. When enabled, this index will increase in to indicate the spectrum analyzer needs to be redrawn. The update only happens when the current value of the index is greater than the previously recorded value. If this index overflows 16-bits and reads zero or if the value is frozen, the software will not update the spectrum analyzer.

As it is limited to 16-bit values, the spectrum analyzer can only be updated a certain amount of times before it overflows. The software appears to check this index a maximum of 45 times per-second during playback, so the Music Record/Jukebox can play songs up about 18:30 long without issue.

Index 0x009B - GBA Speaker Volume db
Adjusts the output volume from the GBA speakers in the range of -20 to +19 db. The index itself goes from 0xFFEC as the minimum to 0x0013 as the maximum.

Index 0x009C - CompactFlash Detection Flag
Determines whether a CompactFlash card has been inserted into the cartridge. Any non-zero value indicates the card cannot be detected.

Index 0x009D - Battery Level
Returns the current level of the AA battery inside the cartridge. Has 3 levels total with the values 0x02 representing 1 bar, 0x01 representing 2 bars, and 0x00 representing 3 bars.

Index 0x00A0 - Current File Track Number
Returns the current file track number. This is determined by how the cartridge arranges files, not by any metadata from the file itself. For Music, Voice Memos, and Karaoke files, this value is used for playback purposes. For Music and Voice Memos, this value is also used during recording. When recording Karaoke files, however, indices 0x0102 and 0x0103 are used instead.

Index 0x00AC - Current Number of Music Files Detected
Returns the current number of Music Files detected on the CompactFlash card.

Index 0x00AE - Current Number of Voice Memo Files Detected
Returns the current number of Voice Memo Files detected on the CompactFlash card.

Index 0x00AF - Current Number of Karaoke Files Detected
Returns the current number of Karaoke Files detected on the CompactFlash card.

Index 0x0100 - Audio Index Length
Determines how many indices to read from 0x102 and beyond for audio input/output data.

Index 0x0101 - CompactFlash Format Progress / CompactFlash Access Progress
Appears to indicate the progress of certain tasks involving the CompactFlash card. For formatting the card, this index represents the overall progress of that process from 0% to 100% using the range 0x0000 through 0x8000. For playing and recording audio data, it seems to determine when certain chunks are finished using a range of 0x0000 through 0x4000.

Index 0x0102 - Current Karaoke File Number for Recording (Hundreds Value)
Returns 8-bits representing the current file number (in hundreds) for recording Karaoke files. It has an unusual offset not seen in the 0x00A0 index. It can be calculated as the following:

INDEX = (((CURRENT_FILE / 100) + 0xA6) AND 0xFF)

Index 0x0103 - Current Karaoke File Number for Recording (Tens and Ones Values)
Returns 8-bits representing the current file number (in tens and ones) for recording Karaoke files. It has an unusual offset not seen in the 0x00A0 index. It can be calculated as the following:

INDEX = (((CURRENT_FILE modulo 100) + 0xA8) AND 0xFF)

Index 0x01C8 - General Configuration Settings
Stores various flags that represent user-changeable settings such as the software's wallpaper, whether to use the Game Boy's speakers vs. headphones, and MP3 recording quality. The bits and the values they affect are listed below:

-----------------------------------------------------------
Bits		| Description
-----------------------------------------------------------
Bits 2-3	| Spectrum Analyzer Type (0 = Analyzer #1, 1 = Analyzer #2, 2 = Analyzer #3)
Bits 4-5	| Wallpaper Type (0 = Wallpaper #1, 1 = Wallpaper #2, 2 = Wallpaper #3)
Bit 8		| GBA Speaker Flag (0 = Use Headphones, 1 = Use GBA Speaker)
Bit 9		| MP3 Recording Silence Detection Flag (0 = Off, 1 = On)
Bits 10-11	| MP3 Recording Quality (0 = 128Kbps, 1 = 96Kbps, 2 = 64Kbps)
Bit 14		| Voice Silence Detection Flag (0 = Off, 1 = On)
Bit 15		| Auto Replay Flag (0 = Off, 1 = On)


Index 0x01C9 - Line-In and Microphone Input Levels
Used to calibrate volumes when recording via Line-In or the microphone. The Music Recorder/Jukebox uses an 8-bit value for this calibration. The high byte is used for microphone sensitivity while the low byte is used for Line-In volumes.

Some indices have a widespread range and serve as string data or audio input/output

-----------------------------------------------------------
Index Range	| R/W	| Description
-----------------------------------------------------------
0x0090 - 0x0098	| R	| Spectrum Analyzer Level For Bars 1 - 9 (0x00 = Min, 0x13 = Max)
0x00A1 - 0x00A6	| R/W	| "8.3" DOS-style short name for music file
0x00B0 - 0x00BE	| R/W	| 30 character song title
0x00BF - 0x00CD	| R/W	| 30 character artist name
0x0102+		| R/W	| Audio in/out data for recording/playing

For the string data at 0x00A1 through 0x00CD, the string is terminated by a null character (value 0x00). The strings for the Jukebox use ASCII.

When reading input/output audio data, the software accesses indices starting at 0x0102 and ends at the length specified by index 0x100. For example, if the Audio Index Length is 0x0004, the CPU reads indices 0x0102 through 0x0105 inclusive. Note that the 0x0102 and 0x0103 are also used for other purposes. Depending on the context, it may represent audio sample data or a Karaoke file number.


***************************************************
7. Recording File Formats
***************************************************

The Music Recorder/Jukebox uses 2 different file formats for recording. For Voice Memos and Karaoke, the device encodes audio via IMA ADPCM into a WAV file. This format uses a 11025Hz sample rate, 16-bits per sample, and just one channel.

For Music recorded via the Line-In jack, an MP3 file is generated. Depending on the user's settings, it will have a bit-rate of 128Kbps, 96Kbps, or 64Kbps. It uses ID3v1 to store metadata at the very last 128 bytes of the file. Instead of regular MP3 files, the Music Recorder/Jukebox produces "GB3" files. However, these GB3 files appear to be normal MP3s without a header. This design prevents music from being recorded and copied to a PC and may have been intended to deter piracy.


***************************************************
8. CompactFlash File & Directory Structure
***************************************************

The CompactFlash card used by the Music Recorder/Jukebox contains a FAT-12 filesystem. The hardware is capable of formatting the card as necessary without the need of a PC or any other kind of media writing device. By default, it has a volume label that reads "AGB-MP3    ". 4 folders and 1 file in the root directory are created after a formatting the card:

-----------------------------------------------------------
Name		| Description
-----------------------------------------------------------
ADPCM		| Folder - Holds all Voice Memo recordings
GB3		| Folder - Holds all Music recordings
MP3		| Folder - Holds all user MP3s for playback
SONG		| Folder - Holds all Karaoke recordings
INFO.AGB	| File - Contains filenames for content in the above folders

Despite its name, INFO.AGB contains no executable code intended to run on the GBA. Instead, simply has a list of all the files present for each category of audio. Additionally, it links MP3 and GB3 files to a given Karaoke recording. INFO.AGB is always 15KB exactly and is divided into the following 4 sections:

-----------------------------------------------------------
Offset 		| Description
-----------------------------------------------------------
0x0000		| MP3 + GB3 Folder File List
0x1800		| ADPCM Folder File List
0x2400		| Song Folder File List
0x3000		| Karaoke Link Data

For sections listing filenames, MP3 files use "8.3" DOS-style short names in ASCII. WAV and GB3 files (named sequentially e.g. 0001.WAV or 0002.WAV) use an even shorter "4.3" style in ASCII. Data is stored as strings with no terminating character or padding. The strings are formatted such that they use 16-bit pairs of characters that need to be read LSB first. Do note that the MP3 and GB3 files are listed together rather than separately.

The Karaoke Link Data essentially points to the relevant MP3 or GB3 file that acted as the source of a Karaoke recording. The files here are ordered sequentially according to how the Music Recorder/Jukebox displays Karaoke files for playback. That is to say, the first file listed in INFO.AGB corresponds to the first file viewed from the Karaoke -> Play menu. This seems necessary for the Jukebox as it allows the software to pull up the 30 character song title and artist fields from the MP3 and GB3 files even though it plays the WAV Karaoke recording (which has no such metadata). If the Karaoke Link Data is corrupted or missing, the Music Recorder/Jukebox refuses to play any Karaoke recordings.

The Music Recorder/Jukebox automatically updates INFO.AGB during various operations, such as deleting files. After a reformat, the Music Recorder/Jukebox inserts a blank INFO.AGB in the root directory.
