Thmp3
(New page: <big>thMp3 - mp3lib for nds</big> ==what is this== a total stub for documenting thmp3 library.) |
|||
Line 1: | Line 1: | ||
− | <big>thMp3 - mp3lib for | + | <big>thMp3 - Touhou mp3lib for NDS</big> |
− | == | + | ==What is this== |
− | a | + | Thmp3 is a library for playing mp3s as (BGM) background music in Nintendo DS games with the goals of being simple to use, modular, small, and fast. Some features include: |
+ | * up to 44100 sample rates, 192K bitrates, 16 bit stereo playback possible (however 32000 is more reliable at this time) | ||
+ | * m3u support, playlist manager | ||
+ | * ID3v1 supported | ||
+ | * playback position indicator (perfect for rhythm games :D) | ||
+ | * supports streaming audio from FAT, or [[Nitrofs]] | ||
+ | * most work is done on the ARM7 cpu | ||
+ | * small size | ||
+ | * speedy code | ||
+ | * c++ compatibility | ||
+ | |||
+ | drawbacks: | ||
+ | * buffers use a lot of memory | ||
+ | * pcm dma transfers and decoding use some arm9 memory bandwidth | ||
+ | * high bit/sample rates use all or most all of the ARM7 CPU | ||
+ | |||
+ | It may not be the best option for all games, but if you want high quality bgm and have cpu to spare might give it a try. ^^ | ||
+ | |||
+ | Was originally written for the [Thds|Touhou Fangame]] and where it gets it's name. Because of interest from other developers was decided to release as a separate lib. Hopes you find it useful. | ||
+ | |||
+ | Todo: | ||
+ | * add fifo support (this will fix only known bug relating to song switching as well) | ||
+ | * modify decoder assembly language file to write pcm data to two seperate buffers instead of interleaving LRLR | ||
+ | |||
+ | ==Mp3 Functions== | ||
+ | ===ARM9=== | ||
+ | '''mp3Init''' | ||
+ | Initalize mp3 player (on the ARM9 side). Will wait for arm7 to indicate its ready before continuing. Should be called once and only once at start of program. | ||
+ | <source lang="c"> | ||
+ | void mp3Init(void); | ||
+ | </source> | ||
+ | '''mp3Play''' | ||
+ | Start playing the mp3 specified by the filesystem path. <br> | ||
+ | (FAT and/or [[Nitrofs]] should be initialized prior to calling this or any other mp3/playlist functions!) | ||
+ | <source lang="c"> | ||
+ | bool mp3Play(char *filename); | ||
+ | </source> | ||
+ | '''mp3Update''' | ||
+ | This function should be placed in the game's idle loop. It is used to refill the input buffer from the stream as needed. This along with mp3Init, and mp3Play represent the minimal requirements for playing an mp3. ^^ | ||
+ | <source lang="c"> | ||
+ | void mp3Update(void); | ||
+ | </source> | ||
+ | '''mp3Stop''' | ||
+ | Stops a playing an mp3 | ||
+ | <source lang="c"> | ||
+ | void mp3Stop(void); | ||
+ | </source> | ||
+ | '''mp3Queue''' | ||
+ | Sets the next song to play when this one eof's. | ||
+ | <source lang="c"> | ||
+ | void mp3Queue(const char *filename); | ||
+ | </source> | ||
+ | |||
+ | ===ARM7=== | ||
+ | '''mp3Init''' | ||
+ | Initializes the ARM7 side of mp3 decoder. Waits for ARM9 to be initialized before returning. Should be called once in the arm7's main() function before the idle loop.<br> | ||
+ | Will return false if helix decoder fails to initialize. | ||
+ | <source lang="c"> | ||
+ | bool mp3Init(void); | ||
+ | </source> | ||
+ | |||
+ | '''mp3Loop''' | ||
+ | This function should be placed in the ARM7's idle loop. It is here all the real work is done, the function may not always return before the end of each vblank interval so take this into consideration. | ||
+ | <source lang="c"> | ||
+ | void mp3Loop(void); | ||
+ | </source> | ||
+ | |||
+ | ===Examples=== | ||
+ | <source lang="c"> | ||
+ | mp3Init(); | ||
+ | |||
+ | mp3Play("path/to/your.mp3"); | ||
+ | |||
+ | while(1) { | ||
+ | mp3Update(); | ||
+ | }; | ||
+ | |||
+ | </source> | ||
+ | |||
+ | ==Playlist Functions== | ||
+ | All functions here are for the arm9. | ||
+ | '''mp3PlaylistClear''' | ||
+ | <source lang="c"> | ||
+ | void mp3PlaylistClear(void); | ||
+ | </source> | ||
+ | '''mp3PlaylistAdd''' | ||
+ | <source lang="c"> | ||
+ | void mp3PlaylistAdd(char *filename, char *title); | ||
+ | </source> | ||
+ | '''mp3ReadId3V1''' | ||
+ | <source lang="c"> | ||
+ | bool mp3ReadId3V1(char *filename, ID3V1_T *id3); | ||
+ | </source> | ||
+ | '''mp3GetId3FromFile''' | ||
+ | <source lang="c"> | ||
+ | bool mp3GetId3FromFile(FILE *f, ID3V1_T *id3); | ||
+ | </source> | ||
+ | '''mp3FormatId3''' | ||
+ | <source lang="c"> | ||
+ | void mp3FormatId3(ID3V1_T *id3, char *titlestr); | ||
+ | </source> | ||
+ | '''mp3PlaylistAddDir''' | ||
+ | <source lang="c"> | ||
+ | bool mp3PlaylistAddDir(char *dirpath); | ||
+ | </source> | ||
+ | '''mp3PlaylistPlay''' | ||
+ | <source lang="c"> | ||
+ | bool mp3PlaylistPlay(int index); | ||
+ | </source> | ||
+ | '''mp3SubPlay''' | ||
+ | <source lang="c"> | ||
+ | bool mp3SubPlay(char *filename, char *title); | ||
+ | </source> | ||
+ | '''mp3PlaylistAddM3u''' | ||
+ | <source lang="c"> | ||
+ | int mp3PlaylistAddM3u(char *filename); | ||
+ | </source> | ||
+ | '''mp3GetSongPos''' | ||
+ | <source lang="c"> | ||
+ | int mp3GetSongPos(int *mins, int *secs, int *ms); | ||
+ | </source> |
Revision as of 23:59, 17 July 2008
thMp3 - Touhou mp3lib for NDS
Contents |
What is this
Thmp3 is a library for playing mp3s as (BGM) background music in Nintendo DS games with the goals of being simple to use, modular, small, and fast. Some features include:
- up to 44100 sample rates, 192K bitrates, 16 bit stereo playback possible (however 32000 is more reliable at this time)
- m3u support, playlist manager
- ID3v1 supported
- playback position indicator (perfect for rhythm games :D)
- supports streaming audio from FAT, or Nitrofs
- most work is done on the ARM7 cpu
- small size
- speedy code
- c++ compatibility
drawbacks:
- buffers use a lot of memory
- pcm dma transfers and decoding use some arm9 memory bandwidth
- high bit/sample rates use all or most all of the ARM7 CPU
It may not be the best option for all games, but if you want high quality bgm and have cpu to spare might give it a try. ^^
Was originally written for the [Thds|Touhou Fangame]] and where it gets it's name. Because of interest from other developers was decided to release as a separate lib. Hopes you find it useful.
Todo:
- add fifo support (this will fix only known bug relating to song switching as well)
- modify decoder assembly language file to write pcm data to two seperate buffers instead of interleaving LRLR
Mp3 Functions
ARM9
mp3Init Initalize mp3 player (on the ARM9 side). Will wait for arm7 to indicate its ready before continuing. Should be called once and only once at start of program.
void mp3Init(void);
mp3Play
Start playing the mp3 specified by the filesystem path.
(FAT and/or Nitrofs should be initialized prior to calling this or any other mp3/playlist functions!)
bool mp3Play(char *filename);
mp3Update This function should be placed in the game's idle loop. It is used to refill the input buffer from the stream as needed. This along with mp3Init, and mp3Play represent the minimal requirements for playing an mp3. ^^
void mp3Update(void);
mp3Stop Stops a playing an mp3
void mp3Stop(void);
mp3Queue Sets the next song to play when this one eof's.
void mp3Queue(const char *filename);
ARM7
mp3Init
Initializes the ARM7 side of mp3 decoder. Waits for ARM9 to be initialized before returning. Should be called once in the arm7's main() function before the idle loop.
Will return false if helix decoder fails to initialize.
bool mp3Init(void);
mp3Loop This function should be placed in the ARM7's idle loop. It is here all the real work is done, the function may not always return before the end of each vblank interval so take this into consideration.
void mp3Loop(void);
Examples
mp3Init(); mp3Play("path/to/your.mp3"); while(1) { mp3Update(); };
Playlist Functions
All functions here are for the arm9. mp3PlaylistClear
void mp3PlaylistClear(void);
mp3PlaylistAdd
void mp3PlaylistAdd(char *filename, char *title);
mp3ReadId3V1
bool mp3ReadId3V1(char *filename, ID3V1_T *id3);
mp3GetId3FromFile
bool mp3GetId3FromFile(FILE *f, ID3V1_T *id3);
mp3FormatId3
void mp3FormatId3(ID3V1_T *id3, char *titlestr);
mp3PlaylistAddDir
bool mp3PlaylistAddDir(char *dirpath);
mp3PlaylistPlay
bool mp3PlaylistPlay(int index);
mp3SubPlay
bool mp3SubPlay(char *filename, char *title);
mp3PlaylistAddM3u
int mp3PlaylistAddM3u(char *filename);
mp3GetSongPos
int mp3GetSongPos(int *mins, int *secs, int *ms);