module SunVox

Defined in:

module.cr
note.cr
pattern.cr
slot.cr
sunvox.cr

Constant Summary

BUFFER_SIZE = 1024

CURRENT_VERSION_MAJOR = 2

CURRENT_VERSION_MINOR = 1

CURRENT_VERSION_MINOR2 = 4

DEFAULT_CHANNELS = 2

DEFAULT_CONFIG = ""

DEFAULT_FREQ = 44100

MAX_SLOTS = 16

NO_MODULE = -1

OUTPUT_MODULE = 0

Class Method Summary

• .audio_callback(buf : Bytes | Slice(Int16) | Slice(Float32), frames : Int32, latency : Int32 = 0, out_time : UInt32 = ticks) : Int32

  Gets the next piece of SunVox audio from the Output module (requires offline: true).

• .audio_callback2(out_buf : Bytes | Slice(Int16) | Slice(Float32), frames : Int32, in_buf : Bytes | Slice(Int16) | Slice(Float32), in_type : SampleType = SampleType::Int16, in_channels : Int32 = DEFAULT_CHANNELS, latency : Int32 = 0, out_time : UInt32 = ticks) : Int32

  Sends audio to the Input module and receives filtered audio from the Output module (requires offline: true).

• .autostop?(slot : Slot | Int32) : Bool

  Returns true if autostop is enabled on slot.

• .close_slot(slot : Slot | Int32) : Nil

  Closes a slot.

• .connect_module(slot : Slot | Int32, src : Module | Int32, dest : Module | Int32) : Bool

  Connect a module src to a module dest.

• .disconnect_module(slot : Slot | Int32, src : Module | Int32, dest : Module | Int32) : Bool

  Disconnect a module src from a module dest.

• .end_of_song?(slot : Slot | Int32) : Bool

  Is the song over and the end has been reached?

• .engine_version
• .export_to_wav(slot : Slot | Int32, song_len_frames : Int, out_filename : String | Path)
• .find_module(slot : Slot | Int32, name : String) : Int32

  Find a module in a slot by name (returns -1 if not found).

• .find_pattern(slot : Slot | Int32, name : String) : Int32

  Finds the pattern in slot by name (returns -1 if not found).

• .frequency_to_pitch(in_freq)
• .get_base_version(slot : Slot | Int32)

  Gets the SunVox version used to create the project in slot.

• .get_current_line(slot : Slot | Int32)

  The current line the playhead is at.

• .get_current_line2(slot : Slot | Int32)

  The current line the playhead is at in fixed-point 27.5 format.

• .get_current_signal_level(slot : Slot | Int32, channel : Int32 = 0) : Int32

  Gets the current output signal level (0..255).

• .get_log(bytes : Int32 = 4096) : String

  Gets the debug log messages.

• .get_module_color(slot : Slot | Int32, module_num : Module | Int32) : Int32

  Get the color of a module in 0xBBGGRR format.

• .get_module_ctl_group(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32) : Int32

  Get the group number of a module's controller.

• .get_module_ctl_max(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32, scaled : Bool | CtlScale | Int32 = false) : Int32

  Get the maximum value of a module's controller.

• .get_module_ctl_min(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32, scaled : Bool | CtlScale | Int32 = false) : Int32

  Get the minimum value of a module's controller.

• .get_module_ctl_name(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32) : String

  Get the name of a module's controller.

• .get_module_ctl_offset(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32) : Int32

  Get the display value offset of a module's controller.

• .get_module_ctl_type(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32) : CtlType

  Get the type of a module's controller (CtlType::Normal or CtlType::Selector).

• .get_module_ctl_value(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32, scaled : Bool | CtlScale | Int32 = false) : Int32

  Get the value of a module's controller (scaled can be a Bool, CtlScale, or 0..2).

• .get_module_curve(slot : Slot | Int32, module_num : Module | Int32, curve_num : Int32, length : Int32 = 257) : Slice(Float32)

  Get the curve data (Slice(Float32)) from a module.

• .get_module_finetune(slot : Slot | Int32, module_num : Module | Int32) : NamedTuple(finetune: Int32, relative_note: Int32)

  Get module's {finetune, relative_note} values.

• .get_module_flags(slot : Slot | Int32, module_num : Module | Int32) : UInt32

  Get the flags set on a module.

• .get_module_inputs(slot : Slot | Int32, module_num : Module | Int32) : Slice(Int32)

  A slice of all input link slots a module has (entries may be -1 if unconnected).

• .get_module_inputs_number(slot : Slot | Int32, module_num : Module | Int32) : Int32

  The number of module input link slots.

• .get_module_name(slot : Slot | Int32, module_num : Module | Int32) : String

  Gets the name of a module.

• .get_module_outputs(slot : Slot | Int32, module_num : Module | Int32) : Slice(Int32)

  A slice of all output link slots a module has (entries may be -1 if unconnected).

• .get_module_outputs_number(slot : Slot | Int32, module_num : Module | Int32) : Int32

  The number of module output link slots.

• .get_module_scope(slot : Slot | Int32, module_num : Module | Int32, channel : Int32 = 0, samples_to_read : Int32 = 1024) : Slice(Int16)

  Get the raw audio output scope values (Slice(Int16)) for a module.

• .get_module_type(slot : Slot | Int32, module_num : Module | Int32) : String

  Gets the type string of a module (e.g.

• .get_module_xy(slot : Slot | Int32, module_num : Module | Int32) : NamedTuple(x: Int32, y: Int32)

  Get the {x, y} position of a module.

• .get_number_of_module_ctls(slot : Slot | Int32, module_num : Module | Int32) : Int32

  Get the number of controllers a module has.

• .get_number_of_modules(slot : Slot | Int32)

  The number of module slots in slot.

• .get_number_of_patterns(slot : Slot | Int32)

  Gets the number of pattern slots in slot.

• .get_pattern_data(slot : Slot | Int32, pattern_num : Pattern | Int32) : Array(Array(SunVox::Event))

  Get the event data, separated by tracks (Array(Array(SunVox::Event))).

• .get_pattern_event(slot : Slot | Int32, pat_num : Pattern | Int32, track : Int32, line : Int32, column : PatternColumn | Int32) : Int32

  Reads a field (column) from the pattern event at (track, line).

• .get_pattern_lines(slot : Slot | Int32, pattern_num : Pattern | Int32) : Int32

  Gets the number of lines in a pattern.

• .get_pattern_name(slot : Slot | Int32, pattern_num : Pattern | Int32) : String

  Gets the pattern's name.

• .get_pattern_tracks(slot : Slot | Int32, pattern_num : Pattern | Int32) : Int32

  Gets the number of tracks in a pattern.

• .get_pattern_x(slot : Slot | Int32, pat_num : Pattern | Int32) : Int32

  Gets the pattern's starting line (X coordinate on timeline).

• .get_pattern_y(slot : Slot | Int32, pat_num : Pattern | Int32) : Int32

  Gets the pattern's vertical position (Y coordinate on timeline).

• .get_raw_pattern_data(slot : Slot | Int32, pattern_num : Pattern | Int32) : Slice(LibSunVox::Event)

  Returns the raw mutable pattern buffer (Slice(LibSunVox::Event)).

• .get_sampler_par(slot : Slot | Int32, sampler_module_num : Module | Int32, sample_slot : Int32, par : SamplerParam | Int32) : Int32

  Gets a sample parameter from a Sampler module.

• .get_song_bpm(slot : Slot | Int32)

  Gets the BPM of the song in slot.

• .get_song_length(slot : Slot | Int32) : Time::Span

  Get the length of the song in seconds as a Time::Span.

• .get_song_length_frames(slot : Slot | Int32)

  The total length in frames of the song in slot.

• .get_song_length_lines(slot : Slot | Int32)

  The total song length in lines of slot.

• .get_song_name(slot : Slot | Int32) : String

  Gets the name of the song in slot.

• .get_song_tpl(slot : Slot | Int32)

  Gets the TPL (Ticks Per Line) of the song in slot.

• .get_volume(slot : Slot | Int32) : Int32

  Queries the current volume of slot (0..256).

• .load(slot : Slot | Int32, filename : String | Path) : Nil

  Loads a project file from disk into a slot.

• .load_from_memory(slot : Slot | Int32, data : Bytes) : Nil

  Loads a project from a memory buffer (Bytes) into a slot.

• .load_module(slot : Slot | Int32, filename : String | Path, x = 512, y = 512, z = 0) : Int32

  Load a module from a file (sunsynth, xi, wav, aiff, ogg, mp3, flac).

• .load_module_from_memory(slot : Slot | Int32, data : Bytes, x = 512, y = 512, z = 0) : Int32

  Load a module or sample from a memory block (Bytes).

• .lock_slot(slot : Slot | Int32) : Nil

  Locks the slot for thread-safe modification.

• .metamodule_load(slot : Slot | Int32, module_num : Module | Int32, filename : String | Path) : Nil

  Loads a file (sunvox, mod, xm, midi) into a MetaModule.

• .metamodule_load_from_memory(slot : Slot | Int32, module_num : Module | Int32, data : Bytes) : Nil

  Loads a file from memory (Bytes) into a MetaModule.

• .module_bypass?(slot : Slot | Int32, module_num : Module | Int32) : Bool
• .module_effect?(slot : Slot | Int32, module_num : Module | Int32) : Bool
• .module_exists?(slot : Slot | Int32, module_num : Module | Int32) : Bool
• .module_generator?(slot : Slot | Int32, module_num : Module | Int32) : Bool
• .module_mute?(slot : Slot | Int32, module_num : Module | Int32) : Bool
• .module_solo?(slot : Slot | Int32, module_num : Module | Int32) : Bool
• .new_module(slot : Slot | Int32, type : ModuleType | String, name = "", x = 512, y = 512, z = 0) : Int32

  Create a new module in slot.

• .new_pattern(slot : Slot | Int32, clone : Pattern | Int32 = -1, x : Int32 = 0, y : Int32 = 0, tracks : Int32 = 4, lines : Int32 = 32, icon_seed : Int32 = 0, name : String = "") : Int32

  Creates a new pattern in slot.

• .offline?
• .open_slot(slot : Slot | Int32 = Slot::Zero) : Slot

  Opens a slot (defaults to Slot::Zero) and returns the Slot.

• .open_slot(slot : Slot | Int32 = Slot::Zero, & : Slot -> )

  Opens a slot for the duration of the block and ensures it is closed afterwards.

• .open_slots : Array(Slot)

  Returns an array of all currently open Slots.

• .pattern_mute(slot : Slot | Int32, pattern_num : Pattern | Int32, mute : Bool = true) : Bool

  Mute/Unmute the pattern.

• .pattern_muted?(slot : Slot | Int32, pattern_num : Pattern | Int32) : Bool

  Queries whether pattern_num is currently muted without changing its state.

• .pause(slot : Slot | Int32)

  Pauses the playback at the current line.

• .pitch_to_frequency(in_pitch)
• .play(slot : Slot | Int32)

  Plays the current song from the current line.

• .play_from_beginning(slot : Slot | Int32)

  Plays the current song from the beginning (line 0).

• .remove_module(slot : Slot | Int32, module_num : Module | Int32) : Bool

  Remove the module module_num in slot.

• .remove_pattern(slot : Slot | Int32, pat_num : Pattern | Int32) : Bool

  Removes a pattern in slot.

• .repeats?(slot : Slot | Int32) : Bool

  Returns whether or not autostop is set (preserved for backwards compatibility).

• .resume(slot : Slot | Int32)

  Resumes playback from a paused state.

• .rewind(slot : Slot | Int32, line_num : Int32)

  Alias for .skip_to_line.

• .sample_rate
• .sample_size
• .sampler_load(slot : Slot | Int32, sampler_module_num : Module | Int32, filename : String | Path, sample_slot = -1) : Nil

  Loads a file into a Sampler (xi, wav, aiff, ogg, mp3, flac).

• .sampler_load_from_memory(slot : Slot | Int32, sampler_module_num : Module | Int32, data : Bytes, sample_slot = -1) : Nil

  Loads a sample from memory (Bytes) into a Sampler module.

• .sampler_par(slot : Slot | Int32, sampler_module_num : Module | Int32, sample_slot : Int32, par : SamplerParam | Int32, par_val : Int32 = 0, set : Bool = false) : Int32

  Gets or sets a sample parameter on a Sampler module (sv_sampler_par).

• .save(slot : Slot | Int32, filename : String | Path) : Nil

  Saves the project in slot to a file on disk.

• .save_to_memory(slot : Slot | Int32) : Bytes

  Saves the project in slot to a newly allocated Bytes slice in memory.

• .send_event(slot : Slot | Int32, track_num : Int32, note : Note, velocity : Int, module_num : Module | Int = -1, ctl : Int = 0, effect : Int = 0, ctl_value : Int = 0)

  Sends an event to SunVox.

• .send_event(slot : Slot | Int32, track_num : Int32, note : Int32, velocity : Int, module_num : Module | Int = -1, ctl : Int = 0, effect : Int = 0, ctl_value : Int = 0)

  Sends an event to SunVox.

• .send_event(slot : Slot | Int32, track_num : Int32, event : Event)

  Sends an Event record to SunVox on track_num.

• .set_autostop(slot : Slot | Int32, autostop : Bool) : Nil

  Enables or disables autostop on slot.

• .set_event_time(slot : Slot | Int32, timestamp : UInt32 = 0_u32, set = true)

  Sets the timestamp of events to be sent by .send_event.

• .set_module_color(slot : Slot | Int32, module_num : Module | Int32, color : Int32) : Nil

  Set the color of a module in 0xBBGGRR format.

• .set_module_ctl_value(slot : Slot | Int32, module_num : Module | Int32, ctl_num : Int32, val : Int32, scaled : Bool | CtlScale | Int32 = false) : Nil

  Set the value of a module's controller (sv_set_module_ctl_value).

• .set_module_curve(slot : Slot | Int32, module_num : Module | Int32, curve_num : Int32, curve_data : Slice(Float32)) : Int32

  Set the curve data of a module.

• .set_module_finetune(slot : Slot | Int32, module_num : Module | Int32, finetune : Int32) : Nil

  Set the module's finetune (-256..256) immediately.

• .set_module_name(slot : Slot | Int32, module_num : Module | Int32, name : String) : Nil

  Sets the name of a module.

• .set_module_relnote(slot : Slot | Int32, module_num : Module | Int32, relative_note : Int32) : Nil

  Set the module's relative note (transposition) immediately.

• .set_module_xy(slot : Slot | Int32, module_num : Module | Int32, x : Int32, y : Int32) : Nil

  Set the (x, y) position of a module.

• .set_pattern_event(slot : Slot | Int32, pat_num : Pattern | Int32, track : Int32, line : Int32, nn : Int32 = -1, vv : Int32 = -1, mm : Int32 = -1, ccee : Int32 = -1, xxyy : Int32 = -1) : Nil

  Writes a pattern event to the cell at (track, line).

• .set_pattern_name(slot : Slot | Int32, pattern_num : Pattern | Int32, name : String) : Bool

  Sets the pattern's name.

• .set_pattern_size(slot : Slot | Int32, pattern_num : Pattern | Int32, tracks : Int32 = -1, lines : Int32 = -1) : Bool

  Sets the number of tracks and/or lines of a pattern (-1 leaves unchanged).

• .set_pattern_xy(slot : Slot | Int32, pat_num : Pattern | Int32, x : Int32, y : Int32) : Bool

  Sets the pattern's (x, y) coordinates on the timeline.

• .set_repeat(slot : Slot | Int32, bool : Bool) : Nil

  Sets autostop flag (preserved for backwards compatibility).

• .set_sampler_par(slot : Slot | Int32, sampler_module_num : Module | Int32, sample_slot : Int32, par : SamplerParam | Int32, val : Int32) : Int32

  Sets a sample parameter on a Sampler module and returns the previous value.

• .set_song_name(slot : Slot | Int32, name : String) : Nil

  Sets the name of the song in slot.

• .skip_to_line(slot : Slot | Int32, line_num : Int32)

  Jumps the current position of the playhead to a line number.

• .slot_open?(slot : Slot | Int32) : Bool

  Returns true if slot is currently open.

• .start_engine(config = DEFAULT_CONFIG, freq = DEFAULT_FREQ, channels = DEFAULT_CHANNELS, no_debug_output = false, offline = false, sample_type = SampleType::Int16, one_thread = false)

  Starts up the SunVox Engine.

• .start_engine(config = DEFAULT_CONFIG, freq = DEFAULT_FREQ, channels = DEFAULT_CHANNELS, no_debug_output = false, offline = false, sample_type = SampleType::Int16, one_thread = false, &)

  Starts the SunVox Engine for the duration of the block and ensures .stop_engine is called afterwards.

• .started?
• .stop(slot : Slot | Int32)

  Stops the current song from playing.

• .stop_engine

  Shuts down the engine and closes all open slots.

• .sync_resume(slot : Slot | Int32)

  Waits for sync (pattern effect 0x33 on any slot) and resumes the audio stream on slot.

• .ticks : UInt32

  The current system tick.

• .ticks_per_second : UInt32

  How many system ticks happen per second.

• .time_map(slot : Slot | Int32, start_line : Int32, len : Int32, flags : TimeMapFlags | Int32 = TimeMapFlags::Speed) : Slice(UInt32)

  Gets the project time map for len lines starting at start_line.

• .unlock_slot(slot : Slot | Int32) : Nil

  Unlocks the slot after modification.

• .update_input
• .version_string : String

  Formatted version string of the active SunVox engine (e.g.

• .volume(slot : Slot | Int32, volume : Int) : Int32

  Sets the output volume of the slot (0..256).

• .vplayer_load(slot : Slot | Int32, module_num : Module | Int32, filename : String | Path) : Nil

  Loads an OGG file into a Vorbis Player module.

• .vplayer_load_from_memory(slot : Slot | Int32, module_num : Module | Int32, data : Bytes) : Nil

  Loads an OGG file from memory (Bytes) into a Vorbis Player module.

Class Method Detail