{"id":15722656,"url":"https://github.com/selimanac/defold-modplayer","last_synced_at":"2025-04-20T23:31:07.213Z","repository":{"id":152789727,"uuid":"186812477","full_name":"selimanac/defold-modplayer","owner":"selimanac","description":"MOD/XM Module Player for Defold Engine","archived":false,"fork":false,"pushed_at":"2019-06-23T08:34:21.000Z","size":3261,"stargazers_count":12,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T06:34:31.764Z","etag":null,"topics":["chiptune","chiptune-player","defold","defold-game-engine","defold-library","module-player","player"],"latest_commit_sha":null,"homepage":"https://selimanac.github.io/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/selimanac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-15T11:27:34.000Z","updated_at":"2024-10-08T13:13:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"7e7a3f47-da6e-4f07-9ee0-a9c6580dac44","html_url":"https://github.com/selimanac/defold-modplayer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimanac%2Fdefold-modplayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimanac%2Fdefold-modplayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimanac%2Fdefold-modplayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimanac%2Fdefold-modplayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/selimanac","download_url":"https://codeload.github.com/selimanac/defold-modplayer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249977433,"owners_count":21354859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chiptune","chiptune-player","defold","defold-game-engine","defold-library","module-player","player"],"created_at":"2024-10-03T22:08:47.289Z","updated_at":"2025-04-20T23:31:06.751Z","avatar_url":"https://github.com/selimanac.png","language":"C","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![ModPlayer](https://github.com/selimanac/defold-modplayer/blob/master/assets/screenshots/defoldheader.png?raw=true)\n\n\n\nThis is chiptune player native extension for [Defold Engine](https://www.defold.com/). ModPlayer can load and play .XM and .MOD file formats. Extension supported MacOS, Windows, Linux*, Android, iOS and [HTML5](#html5-bundle).  \n\n**Caution:** This extension is not battle tested yet and you should consider it as alpha release. It may contain bugs.\n\n\n## Installation\n\nInstallation requires a few steps. \n\n#### 1- Add Dependency\n\nYou can use the ModPlayer extension in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/).  \nOpen your game.project file and in the dependencies field under project add:\n\n\u003ehttps://github.com/selimanac/defold-modplayer/archive/master.zip\n\n#### 2- Bundle Resources Path\n\nOpen your game.project file and in the [Bundle Resources](https://www.defold.com/manuals/project-settings/) field under project add:\n\n\u003e/res\n\n![Bundle](https://github.com/selimanac/defold-modplayer/blob/master/assets/screenshots/bundle.png?raw=true)\n\n#### 3- Create Folders\n\nCreate `/res/common/assets` folders in your project root. Then you can place your .xm and .mod files here. You can add subfolders as you like; `/res/common/assets/musics`\n\n![Bundle](https://github.com/selimanac/defold-modplayer/blob/master/assets/screenshots/folders.png?raw=true)\n\n\n## Notes \u0026 Known Issues\n\n* Loading and parsing is blocker. It will block the main thread (UI thread). Since the mod files are small it is better to load them when bootstraping or preloading. It may cause a pause on UI.\n* Loading and parsing XM files much more faster then mod files. Use XM if possible. (Tested with same tracker file as .mod and .xm) \n* Not %100 compatible with every MOD or XM files. \n* I couldn't find a way to retrieve build path when developing on Defold Editor. You have to provide a full path to `player.build_path(\"\u003cFULL_PATH\u003e/res/common/assets/\")` function for **working on Defold Editor only**. It doesn't required when bundling.\n* Different platform bundles didn't tested very well.\n\t* MacOS: Long run.\n\t* iOS: Long run. \n\t* Windows: Short run. Tested on [Wine](https://www.winehq.org/) \n\t* Android: Short run. \n\t* Linux: I couldn't manage to have sound on my VMs. But app is successfully load the files and run on Debian and Ubuntu\t\n* Hashtable is limited to 10 elements. I think it is more than enough. It is a bad practice to load or play more than two music files at the same time. \n* Currently, it is not possible to Build HTML5 on the Defold Editor with mod music. You can build it for testing, but can't load the the musics.\n\t\n## Example\n\nSee the [example folder](https://github.com/selimanac/defold-modplayer/tree/master/example) for simple usage.   \nFor more examples: [https://github.com/selimanac/defold-modplayer-examples](https://github.com/selimanac/defold-modplayer-examples)  \nNanowar game example: [https://github.com/selimanac/nanowar-modplayer](https://github.com/selimanac/nanowar-modplayer)\n\n\n```lua\n\n\tplayer.master_volume(1.0) -- Set master volume for musics ( 0.0 -\u003e 1.0 is max level)\n\tlocal music = player.load_music(\"bb.xm\") -- Load mod file and assign it is ID\n\tplayer.play_music(music) -- Play mod file\n\tplayer.music_volume(music, 0.5) -- Set volume for music ( 0.0 -\u003e 1.0 is max level)\n\tplayer.music_pitch(music, 1.0) -- Set pitch for a music (1.0 is base level)\n\tprint(\"Music length: \", player.music_lenght(music)) -- Get music time length (in seconds)\n\t\n```\n\n## HTML5 Bundle\n\nUnfortunately, it is not possible to build HTML5 on the Defold Editor with mod music(You can build it for testing, but can't load the musics). But you can bundle as HTML5 from the Editor with mod music.\n\nBundling for HTML5 is require of editing `archive_files.json` file. [More info about the issue is here.](https://forum.defold.com/t/reading-files-from-res-common-folder-with-emscripten/55056).   \nYou can use a script or you can edit it manually.\n\n### - Python Script\n\nI wrote a small [python script](https://github.com/selimanac/modplayer-html5-example/blob/master/mod_file_parser.py) for updating `archive_files.json`file with music files data. You can find it here: https://github.com/selimanac/modplayer-html5-example/blob/master/mod_file_parser.py\n\n* Put [this](https://github.com/selimanac/modplayer-html5-example/blob/master/mod_file_parser.py) file alongside the index.html in the root of your HTML5 Bundle\n* Run it with /assets/ path  \n    `\u003e python mod_file_parser.py /assets/audio`\n* It will update the /archive/archive_files.json file with music data\n\n### - Manual\n\n* Bundle you project as usual by using `Project \u003e Bundle \u003e HTML5` from the Defold Editor\n* Open `archive/archive_files.json` file from bundled folder \n* Add your music files into `archive_files.json` file with their names and sizes.\n\n```\n{\n    \"name\": \"level_1.xm\", \t\u003c- Name of your file for loading from Defold\n    \"size\": 42940,\t\t\t\u003c- Actual size of the file (bytes) \n    \"pieces\": [\n        {\n            \"name\": \"../assets/audio/level_1.xm\", \u003c- Relative path to your mod files\n            \"offset\": 0\n        }\n    ]\n}\n```        \n\nExample HTML5 project is [here](https://github.com/selimanac/modplayer-html5-example) and example archive_files.json is [here](https://github.com/selimanac/modplayer-html5-example/blob/master/archive/archive_files.json).\n\n## API\n\n#### player.build_path(full_path:string)\n\n**!- Don't set this when bundling -!**  \n\nOnly required when developing on Defold Editor. `\u003cFULL_PATH\u003e` ([absolute path](https://en.wikipedia.org/wiki/Path_(computing))) is the full path of your project folder/directory.  \nDon't forget to add **trailing `/`**.   \n\n\n```lua\nplayer.build_path(\"\u003cFULL_PATH\u003e/res/common/assets/\") -- Set build path when working on Editor only s\n```\n\n##### Examples  \nWindows:   \n`player.build_path(\"C:/Users/user_name/your_project_path/res/common/assets/\")`\n \n*nix:  \n`player.build_path(\"/Users/user_name/your_project_path/res/common/assets/\")`\n\nWe don't need it when bundling:\n\n```lua\nlocal is_development = false -- If you are building on Defold Editor then set it true. If you are bundling set it false\nif is_development then\n\tplayer.build_path(\"\u003cFULL_PATH\u003e/res/common/assets/\") -- Set build path only for Defold Editor\nend\n```\n\n#### player.master_volume(volume:double)\n\nSet master volume for musics ( 0.0 -\u003e 1.0 is max level)\n\n```lua\nplayer.master_volume(1.0)\n```\n\n#### player.load_music(file_name:string)\n\nLoad and parse mod file into memory.\nReturns ID.\n\n```lua\nlocal music = player.load_music(\"your_file_name.xm\") -- Load mod file and assign it is ID[int] \n```\n\n#### player.play_music(id:int)\n\nStart music playing.\n\n```lua\nplayer.play_music(music) \n```\n\n#### player.pause_music(id:int)\n\nPause music playing.\n\n```lua\nplayer.pause_music(music) \n```\n\n#### player.resume_music(id:int)\n\nResume playing \"paused\" music\n\n```lua\nplayer.resume_music(music)\n```\n\n#### player.music_volume(id:int, volume:double)\n\nSet volume for music ( 0.0 -\u003e 1.0 is max level)\n\n```lua\nplayer.music_volume(music, 0.5)\n```\n\n#### player.music_pitch(id:int, pitch:double)\n\nSet pitch for a music (1.0 is base level). \n\n```lua\nplayer.music_pitch(music, 1.0) \n```\n\n#### player.music_lenght(id:int)\n\nGet music time length (in seconds)\n\n```lua\nprint(\"Music length: \", player.music_lenght(music))\n```\n\n#### player.music_played(id:int)\n\nGet current music time played (in seconds)\n\n```lua\nprint(\"Played : \", player.music_played(music))\n```\n\n#### player.music_loop(loop:int)\n\nSet music loop count (loop repeats) NOTE: If set to -1, means infinite loop. Default is -1 (infinite)\n\n```lua\nplayer.music_loop(music, 1)\n```\n\n#### player.is_music_playing(id:int)\n\nCheck if music is playing. Also returns `false` if music is not loaded or unloaded.\n\n```lua\nprint(\"is Playing:\", player.is_music_playing(music)) \n```\n\n#### player.stop_music(id:int)\n\nStop music playing\n\n```lua\nplayer.stop_music(music) \n```\n\n#### player.unload_music(id:int)\n\nUnload music from memory\n\n```lua\nplayer.unload_music(music)\n```\n\n#### player.xm_volume(id:int, volume:double, amplification:double)\n\nOnly for XM files. You can change the samples volume, but it may cause a clipping. You can balance it with amplification. Some bad modules may still clip. Default values; volume 1.0, amplification 0.25.\nUse it with caution!\n\n```lua\nplayer.xm_volume(music, 2.5, 0.15)\n```\n\n## Dependencies\n\n* [miniaudio](https://github.com/dr-soft/miniaudio) (slightly modified version)\n* [raudio](https://github.com/raysan5/raylib/blob/master/src/raudio.c) (heavily modified version)\n* [jar_mod](https://github.com/kd7tck/jar/blob/master/jar_mod.h) (slightly modified version)\n* [jar_xm](https://github.com/kd7tck/jar/blob/master/jar_xm.h) (slightly modified version)\n* [hashtable](https://github.com/JCash/containers/blob/master/src/jc/hashtable.h)\n\n**Thanks to all Defold team for their great support.**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselimanac%2Fdefold-modplayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fselimanac%2Fdefold-modplayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselimanac%2Fdefold-modplayer/lists"}