SunVOSC and SunVox DLL internals

In order to successfully work with SunVox DLL via OSC, it is important to be aware of some of the internals involved that affect the characteristics of performance.

Slots

  • In each instance of SunVox DLL, there are 4 playback slots.
  • All slots share the same audio output.
  • Each slot has independent state for everything else, including modules, patterns, tempo, and playback state.

Internal pattern

  • SunVox DLL maintains a single internal pattern that is used for playback of notes using the sv_send_event API call.
  • It contains 16 tracks.
  • Notes are played immediately upon sending an event, rather than when the next row is scheduled to play.
  • You cannot send multiple events to the internal pattern that rely on another track. For example, this means if you send a note to track 0, then send an effect to track 1 using the “previous track” note command, no effect will actually occur.
  • SunVOSC exposes the internal pattern for purposes of playing notes as early as possible, such as in the case of immediate performance of notes generated by a MIDI device.

Playback patterns

  • SunVOSC maintains one or more playback patterns in slot(s) used to play events queued via OSC.
  • Each has 16 tracks (or the maximum supported by the current version of SunVox).
  • Each have the same number of rows, and are played in a continuous loop.
  • Each is positioned at (0, 0) on the timeline.
  • Actual rows are used to implement virtual rows by way of clearing and reusing rows that were already played.
  • Peer initializes SunVOSC by sending a message to initialize a playback slot, specifying number of patterns and number of actual rows per pattern.
  • The following sequence is repeated during playback:
    1. Peer sends message(s) to fill virtual row(s) with events.
    2. SunVOSC receives the event(s), and stores or drops each event according to these rules:
      • SunVOSC stores an event into the appropriate playback pattern if its virtual row is greater than the current playback row, and less than the current playback row plus the number of actual rows.
      • SunVOSC silently drops an event if its virtual row is less than or equal to the current playback row, or greater than the current playback row plus the number of actual rows.
    3. Upon detecting that an actual row is being played by SunVox DLL, SunVOSC will do the following:
      • Send a message to peer with the following fields:
        • virtual row number that was just played
        • maximum virtual row now available for queueing future events
      • Initialize the prior actual row with zeros, to prevent playback of past events.
  • Peer is responsible for sending future events in time for them to be stored and not dropped.
  • Peer is responsible for avoiding sending events that are too far in the future and thus would be dropped.

Project patterns

  • If a project is loaded into a SunVOSC slot and it contains patterns that are fully or partially in the positive timeline space, they will be relocated internally to be entirely in the negative timeline space.
  • For projects that already have tracks in the negative space, tracks in positive space will be relocated: the end of all relocated tracks will occur before the beginning of the existing negative tracks.
  • SunVOSC maintains a relocation map, so that any request to play some or all of a row of the original timeline space can be mapped to the relocated space.
  • SunVOSC calculates the maximum number of overlapping patterns in the project, and maintains that number of extra playback patterns dedicated to playing back rows from existing patterns.
  • When a request to play some or all of a row of the original timeline space is received, SunVOSC will copy the tracks from each pattern in that row to playback pattern(s) at the row that immediatey succeeds that which is currently playing.

Timing

Tempo and ticks

  • Upon slot initialization, SunVOSC will set tempo to 125 and ticks-per-line to 1.

    This provide the highest resolution of note scheduling that directly aligns with a standard MIDI beat clock of 24 ticks per quarter note.

  • Peer may set tempo and ticks-per-line at any time by queueing standard SunVox effects.

  • Peer is responsible for maintaining its own knowledge of timing for the purposes of synchronizing with other systems, e.g. generating MIDI clock events.

LFOs

  • SunVox LFOs do not automatically reset during transport commands such as start/stop.
  • Peer is responsible for resetting LFO as needed via the “Set Phase” controller if LFO phase must be deterministic.