etc/furnace
0
0
Fork 0
mirror of https://github.com/tildearrow/furnace.git synced 2024-11-26 14:33:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

update documentation (export options)

Browse source
This commit is contained in:
tildearrow 2024-02-04 17:48:46 -05:00
parent 77f162a0d1
commit 5368b138d3
2 changed files with 86 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
doc/2-interface/export.md Normal file
View file

@ -0,0 +1,85 @@
# export
Furnace allows you to export your song in several formats. this section deals with describing the available export options.
## export audio
this option allows you to export your song in .wav format. I know I know, no .mp3 or .ogg export yet, but you can use a converter.
there are two parameters:
- **Loops**: sets the number of times the song will loop.
- does not have effect if the song ends with `FFxx` effect.
- **Fade out (seconds)**: sets the fade out time when the song is over.
- does not have effect if the song ends with `FFxx` effect.
and three export choices:
- **one file**: exports your song to one .wav file.
- **multiple files (one per chip)**: exports the output of each chip to .wav files.
- **multiple files (one per channel)**: exports the output of each channel to .wav files.
- useful for usage with a channel visualizer such as corrscope.
## export VGM
this option allows exporting to a VGM (Video Game Music) file. these can be played back with VGMPlay (for example).
the following settings exist:
- **format version**: sets the VGM format version to use.
- versions under 1.70 do not support per-chip volumes, and therefore will ignore the Mixer completely.
- other versions may not support all chips.
- use this option if you need to export for a quirky player or parser.
- for example, RYMCast is picky with format versions. if you're going to use this player, select 1.60.
- **loop**: includes loop information. if disabled, the resulting file won't loop.
- **loop trail**: sets how much of the song is written after it loops.
- the reason this exists is to work around a VGM format limitation in where post-loop state isn't recorded at all.
- this may change the song length as it appears on a player.
- **auto-detect**: detect how much to write automatically.
- **add one loop**: add one more loop.
- **custom**: allows you to specify how many ticks to add.
- `0` is effectively none, disabling loop trail completely.
- this option will not appear if the loop modality isn't set to None as there wouldn't be a need to.
- **chips to export**: select which chips are going to be exported.
- due to VGM format limitations, you can only select up to two of each chip type.
- some chips will not be available, either because VGM doesn't support these yet, or because you selected an old format version.
- **add pattern change hints**: this option adds a "hint" when a pattern change occurs. only useful if you're a developer.
- the format of the "hint" data block that gets written is: `67 66 FE ll ll ll ll 01 oo rr pp pp pp ...`
- `ll`: length, a 32-bit little-endian number
- `oo`: order
- `rr`: initial row (a 0Dxx effect is able to select a different row)
- `pp`: pattern index (one per channel)
- **direct stream mode**: this option allows DualPCM to work. don't use this for other chips.
- may or may not play well with hardware VGM players.
click on **click to export** to begin exporting.
## export text
this option allows you to export your song as a text file.
## export ZSM
ZSM (ZSound Music) is a format designed for the Commander X16 to allow hardware playback.
it may contain data for either YM2151 or VERA chips.
Calliope is one of the programs that supports playback of ZSM files.
the following settings are available:
- **Tick Rate (Hz)**: select the tick rate the song will run at.
- I suggest you use the same rate as the song's.
- apparently ZSM doesn't support changing the rate mid-song.
- **loop**: enables loop. if disabled, the song won't loop.
- **optimize size**: removes unnecessary commands to reduce size.
click on **Begin Export** to... you know.
## export command stream
this option exports a text or binary file which contains a dump of the internal command stream produced when playing the song.
it's not really useful, unless you're a developer and want to use a command stream dump for some reason (e.g. writing a hardware sound driver).
- **export (binary)**: exports in Furnace's own command stream format (FCS). see `export-tech.md` in `papers/` for details.
- **export (text)**: exports the command stream as a text file. only useful for analysis, really.

85
doc/2-interface/menu-bar.md
View file

@ -33,13 +33,7 @@ items in _italic_ don't appear in basic mode and are only available in advanced
- Neo Geo CD (DefleMask 1.0+) - Neo Geo CD (DefleMask 1.0+)
- only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost. - only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost.
- **export audio...**: opens the file picker, allowing you to export your song to a .wav file. see next section for more details. - **export**: allows you to export your song into other formats, such as audio files, VGM and more. see the [export](export.md) page for more information.
- **export VGM...**: opens the file picker, allowing you to export your song to a .vgm file. see next section for more details.
- **export text...**: opens the file picker, allowing you to export your song to a .txt file.
- **export ZSM...**: opens the file picker, allowing you to export your song to a .zsm file. see next section for more details.
- only available when there's a YM2151 and/or VERA.
- **export command stream...**: export song data to a command stream file. see next section for more details.
- this option is for developers.
- **manage chips**: opens the [Chip Manager](../8-advanced/chip-manager.md) dialog. - **manage chips**: opens the [Chip Manager](../8-advanced/chip-manager.md) dialog.
@ -54,83 +48,6 @@ items in _italic_ don't appear in basic mode and are only available in advanced
- **exit**: closes Furnace. - **exit**: closes Furnace.
### export audio
this option allows you to export your song in .wav format. I know I know, no .mp3 or .ogg export yet, but you can use a converter.
there are two parameters:
- **Loops**: sets the number of times the song will loop.
- does not have effect if the song ends with `FFxx` effect.
- **Fade out (seconds)**: sets the fade out time when the song is over.
- does not have effect if the song ends with `FFxx` effect.
and three export choices:
- **one file**: exports your song to one .wav file.
- **multiple files (one per chip)**: exports the output of each chip to .wav files.
- **multiple files (one per channel)**: exports the output of each channel to .wav files.
- useful for usage with a channel visualizer such as corrscope.
### export VGM
this option allows exporting to a VGM (Video Game Music) file. these can be played back with VGMPlay (for example).
the following settings exist:
- **format version**: sets the VGM format version to use.
- versions under 1.70 do not support per-chip volumes, and therefore will ignore the Mixer completely.
- other versions may not support all chips.
- use this option if you need to export for a quirky player or parser.
- for example, RYMCast is picky with format versions. if you're going to use this player, select 1.60.
- **loop**: includes loop information. if disabled, the resulting file won't loop.
- **loop trail**: sets how much of the song is written after it loops.
- the reason this exists is to work around a VGM format limitation in where post-loop state isn't recorded at all.
- this may change the song length as it appears on a player.
- **auto-detect**: detect how much to write automatically.
- **add one loop**: add one more loop.
- **custom**: allows you to specify how many ticks to add.
- `0` is effectively none, disabling loop trail completely.
- this option will not appear if the loop modality isn't set to None as there wouldn't be a need to.
- **chips to export**: select which chips are going to be exported.
- due to VGM format limitations, you can only select up to two of each chip type.
- some chips will not be available, either because VGM doesn't support these yet, or because you selected an old format version.
- **add pattern change hints**: this option adds a "hint" when a pattern change occurs. only useful if you're a developer.
- the format of the "hint" data block that gets written is: `67 66 FE ll ll ll ll 01 oo rr pp pp pp ...`
- `ll`: length, a 32-bit little-endian number
- `oo`: order
- `rr`: initial row (a 0Dxx effect is able to select a different row)
- `pp`: pattern index (one per channel)
- **direct stream mode**: this option allows DualPCM to work. don't use this for other chips.
- may or may not play well with hardware VGM players.
click on **click to export** to begin exporting.
### export ZSM
ZSM (ZSound Music) is a format designed for the Commander X16 to allow hardware playback.
it may contain data for either YM2151 or VERA chips.
Calliope is one of the programs that supports playback of ZSM files.
the following settings are available:
- **Tick Rate (Hz)**: select the tick rate the song will run at.
- I suggest you use the same rate as the song's.
- apparently ZSM doesn't support changing the rate mid-song.
- **loop**: enables loop. if disabled, the song won't loop.
- **optimize size**: removes unnecessary commands to reduce size.
click on **Begin Export** to... you know.
### export command stream
this option exports a text or binary file which contains a dump of the internal command stream produced when playing the song.
it's not really useful, unless you're a developer and want to use a command stream dump for some reason (e.g. writing a hardware sound driver).
- **export (binary)**: exports in Furnace's own command stream format (FCS). see `export-tech.md` in `papers/` for details.
- **export (text)**: exports the command stream as a text file. only useful for analysis, really.
## edit ## edit
- **...**: does nothing except prevent accidental clicks on later menu items if the menu is too tall to fit on the program window. - **...**: does nothing except prevent accidental clicks on later menu items if the menu is too tall to fit on the program window.