diff --git a/Using-the-Soundtrack-Tool.md b/Using-the-Soundtrack-Tool.md index 71e24b7..01e2180 100644 --- a/Using-the-Soundtrack-Tool.md +++ b/Using-the-Soundtrack-Tool.md @@ -1,54 +1,32 @@ # Soundtrack Tool -This tool converts a tracker module (e.g. Deflemask) into a format that can be played on-console, usually with a sound driver (e.g. Echo Sound Engine). If you are familiar with [`dmf2esf`](https://github.com/BigEvilCorporation/dmf2esf), this utility serves as a rewrite which supports the newer version(s) of Deflemask DMF format, as well as some extra effects like portamentos. +This tool converts a tracker squence into a format that can be played on-console, usually with a sound driver. If you are familiar with [`dmf2esf`](https://github.com/BigEvilCorporation/dmf2esf), this utility serves as a successor and a rewrite which supports the newer version(s) of Deflemask DMF format. -## Important Notes -`soundtrack` is in daily active development and _will_ break if you use it. The current version is provided for experimental and informational purposes only. +### Supported Tracker Formats +* Deflemask + * DMF file version 27 (exported by Deflemask version 1.1.8) + * Six FM channel + Four PSG mode only (Ch. 3 Special not supported) -## Quick Start -### Basic -This example converts a Deflemask DMF module to an Echo Sound Engine ESF stream, additionally exporting instruments and an asm file (for the `asmx` assembler) which makes it easy to integrate into your project. -``` -reskit soundtrack -i module.dmf -o module.esf -``` -Use `reskit soundtrack --help` to view more options. +### Supported Export Formats +* Echo Sound Engine (ESF) for Sega Mega Drive + * Version 1.68 ([tree c83e424](https://github.com/sikthehedgehog/Echo/tree/c83e424e7736d07690ace2488bf9195ed27f7af4)) + + +`soundtrack` is currently in **alpha** and such is very likely to fail in common scenarios. You can give it a try for your DMF -> ESF conversion requirements, but as of now it may not work for all tracks. In my experience, 80% of tracks using effects supported will play properly. I will fix these issues as I encounter them while converting compositions for my Sega Mega Drive homebrew game, or as issues are reported in the issue tracker. Thank you for your patience! ## Effects Currently Supported * `1xx` Portamento Up * `2xx` Portamento Down +* `8xx` Set panning * `Bxx` Set position jump + * Position jump can only be set once and to a pattern matrix row less than or equal to the current pattern matrix row. This will be converted into an [$FD/$FC ESF event pair](https://github.com/sikthehedgehog/Echo/blob/c83e424e7736d07690ace2488bf9195ed27f7af4/doc/esf.txt#L412), with its own limitations. * `Dxx` Jump to next pattern * `17xx` DAC Enable (FM6) * `20xx` Noise generator mode * `ECxx` Note cut -## Additional Sample Use Cases - -### Change the Instrument Export Location -This example does the same as above but allows you to control where instruments (or "artifacts", secondary files required by the main track) are exported. -``` -reskit soundtrack -i module.dmf -o module.esf --artifact-output-directory instruments/ -``` - -### Change the Label Used for the Main Track -This example allows you to change the label/identifier for the generated code export. This is the label you use in your homebrew game to point to the main track. -``` -reskit soundtrack -i module.dmf -o module.esf --soundtrack-label MuzHeyYa -``` - -The generated asm file you can include in your project then looks similar to this: -``` -; Echo instrument definitions file -; Generated by reskit v0.0.2 - -MuzHeyYa: - incbin 'resources/music/heyya.esf' - -... -``` - -## Supported Tracker Formats (0.0.x) -* Deflemask (DMF version 27, exported by Deflemask version 1.1.8, does not use Ch. 3 Special mode) - -## Supported Consoles/Drivers (0.0.x) -* Echo Sound Engine (ESF) for Sega Megadrive \ No newline at end of file +## Roadmap +The eventual vision of `reskit` is to serve as an ffmpeg-like tool for converting assets to and from 8-bit and 16-bit console media formats. `soundtrack` aims to eventually support the following: +* VGM format conversions + * E.g. VGM to ESF, ESF to VGM. Build a sequence from VGM so that developers can make use of features offered by their sound engines, such as FM and PSG sound effects. + * Highest priority, as many utilities including and other than Deflemask support VGM export. It is essentially an informal interchange format for console music. VGM support will allow `soundtrack` to quickly support a wide variety of sound engines and trackers. \ No newline at end of file