WAV file export.
This module provides an exporter for exporting individual songs in a module to a WAV file. The song is played, the APU is emulated, and the resulting sound samples are written to an output WAV file.
There are two ways of using this module: one-shot and iterative.
One-shot
One-shot mode is done by just calling the exportWav proc. The WAV file is generated in that proc alone according to the given configuration.
Iterative
Iterative mode is done by creating a WavExporter object and then calling the process proc repeatedly until hasWork is false. You can use the progress and progressMax procs to display overall progress of the export.
This mode is preferred for GUI applications, so that you can report progress to the user while the export is in process.
Example:
var config = WavConfig.init() config.filename = "out.wav" var ex = WavExporter.init(module, config) # progressBar.setMax(ex.progressMax) while ex.hasWork(): # progressBar.setValue(ex.progress) ex.process(module)
Types
SongDuration = object case unitInLoops*: bool ## If `true`, then this duration will loop the song a given number of ## times. If `false, then this duration will use a time duration. ## of true: loopAmount*: Positive ## Number of times to loop the song ## of false: timeAmount*: Duration ## Amount of time to play the song for. ##
- Duration of the song to export. The amount can either be specified in number of loops, or a Duration from std/times. Source Edit
WavConfig = object song*: Natural ## Index of the song in the module to export. Default is 0, or the first ## song. ## duration*: SongDuration ## The duration to export. Default is a time unit of 1 minute. ## filename*: string ## Destination filename of the output WAV file. ## samplerate*: Natural ## Output samplerate, in Hertz, of the output WAV file. Must not be 0. ## Default is 44100 Hz. ## channels*: set[ChannelId] ## Set of channels to export. Default is all channels. ## isMono*: bool ## If set to true, the output file will be in mono sound (1 sound channel). ## stereo otherwise. Mono sound conversion is done by averaging the left ## and right channels. Default is false, or stereo sound. ##
- Configuration of the WAV file to create. Source Edit
WavExporter = object
- WavExporter object for iterative mode. An exporter can be created via the init proc. Source Edit
Procs
proc batched(config: WavConfig): seq[WavConfig] {....raises: [], tags: [], forbids: [].}
-
Creates a sequence of WavConfigs where each channel in config gets its own output file. The filename in each of these configs gets a suffix added to the filename, ie $name.ch$channel.$ext.
Use this when exporting each channel separately is desired.
Source Edit func hasWork(ex: WavExporter): bool {....raises: [], tags: [], forbids: [].}
- Returns true if the exporter still has work to do, false otherwise. Source Edit
func init(T: typedesc[WavConfig]): WavConfig
- Initializes a WavConfig with default settings. Source Edit
proc init(T: typedesc[WavExporter]; module: Module; config: WavConfig): WavExporter {. ...raises: [IOError].}
-
Initializes a WavExporter for a given module and config. The output WAV file specified in config is created and ready to be filled with samples.
The export can continue by calling process repeatedly until hasWork returns false.
An IOError will be raised if the output file could not be written to.
Source Edit proc process(ex: var WavExporter; module: Module) {....raises: [IOError], tags: [RootEffect, WriteIOEffect], forbids: [].}
-
Processes a single frame and writes it to the destination WAV file. If the exporter is finished this proc does nothing. Use hasWork to check before calling this proc.
An IOError may be raised if any error occurred during writing to the output WAV file.
Source Edit func progress(ex: WavExporter): int {....raises: [], tags: [], forbids: [].}
- Gets a number representing the total overall progress made towards the export. The number returned will be in the range 0..ex.progressMax. Source Edit
func progressMax(ex: WavExporter): int {....raises: [], tags: [], forbids: [].}
- Gets a number representing the maximum of the values returned by progress. Source Edit
func songDuration(loops: Positive): SongDuration {....raises: [], tags: [], forbids: [].}
- Initializes a song duration with the given number of loops. Source Edit
func songDuration(time: Duration): SongDuration {....raises: [], tags: [], forbids: [].}
- Initializes a song duration with the given time amount Source Edit