ashley
/
reskit
1
0
Fork 0
Code Issues 4 Pull Requests Packages Projects Releases Wiki Activity

Update Using the Soundtrack Tool

master
Ashley N. 2023-09-02 15:18:16 +00:00
parent 7ed7804f46
commit dd33f59397
1 changed files with 18 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
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
## 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.