# VLK Tracker documentation ## Version - Document version 1.0 - VLK Tracker version 1.0 ## Intro VLK tracker is a rather primitive chiptune tracker simulating a virtual chip. Its main usage is for real-time music and effects in retro inspired games and similar applications. It started as an experimental rewrite of snibbetracker and turned into its own thing. It's mainly written in C89 with cJSON as its only dependency. A single savefile consists of up to 128 songs and 128 sound effects and once a vlk soundbank is loaded, you will have everything in it at your fingertips. VLK song sequencers support 4 channels, 16 instruments and 128 patterns, and sound effect sequencers have 1 channel, 1 instrument and 1 pattern. Only one song can play at a time occupying channels 0-3 and sound effects can either play on channel 4 or 5. A prominent feature in VLK Tracker is that random parameters are supported wherever suitable to enhance the variation of its contents, be it for effects, instruments, pitch or pattern jumps and loops. A quite small song can give a lot of variation depending on how it’s constructed in this regard. ## Track view Here notes are added for playback. Each note resides in one of the 4 channels, has an octave number, instrument index and optional effects set. The number of rows for each track can be adjusted in pattern view -> track rows which is set to 16 as default. ## Instrument view Each note needs to have an instrument assigned to produce sound on a channel. ### Effects Effects can be applied on separate notes, or on an instrument where they are applied for every note (J and T excluded). Each time a note is retriggered, any random values will randomized again. - 0XX Arpeggio - 1XX Arpeggio speed - 3XX Portamento - 4XX Vibrato - 7XX Detune - AXX Amplitude - EXX Pitch up - FXX Pitch down - RXX Random effect (J and T excluded) - JXX Jump to track. XX tells which track to target and instrument index the probability. 0-F (8 is 50%). - TXX Jump within track. XX tells which track to target and instrument index the probability. 0-F (8 is 50%). ### Waveforms Each instrument uses one of eight selectable oscillators with a basic waveform to produce sound. The table for representing the waveforms are 16 samples wide and has 8 levels of amplitude. The following waveforms are supplied: - Sine (SIN) amp: 4, 3, 2, 1, 0, 0, 1, 2, 3, 4, 5, 6, 7, 7, 6, 5 - Square (SQU) amp: 7, 7, 7, 7, 7, 7, 7, 7, 0, 0, 0, 0, 0, 0, 0, 0 - Saw (SAW) amp: 7, 7, 6, 6, 5, 5, 4, 4, 3, 3, 2, 2, 1, 1, 0, 0 - Triangle (TRI) amp: 0, 0, 2, 2, 5, 5, 7, 7, 7, 7, 5, 5, 2, 2, 0, 0 - Noise (NOI) has 88200 random samples with 8 levels of amplitude - Pulse 1 (PU1) amp: 7, 7, 7, 7, 7, 7, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 - Pulse 2 (PU2) amp: 7, 7, 7, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 - Pulse 3 (PU3) amp: 7, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ### Wavetable Each instrument has 8 wavetable slots where a waveform, piched noise, note-diff can be applied. The wavetable can be set to loop, or as a oneshot. Wavetable speed is 0-F. Amplitude envelope: Is represented as ADSR (attack, decay, sustain and release) and has 4 values between 0-7 to represent these. An overall speed of the envelope can be set with values 0-7. ### Pattern view - Patterns and General settings - seq: select which sequencer to be active. - submode: Change between music (0) and sfx (1) submodes. - reset seq: Reset sequencer back to default settings removing all notes etc. - beat: Select which rythm the song should go in. 0 values are skipped, so the default 4400 is 4/4 tempo. - active patterns: Select how many active rows tracks contains before jumping to the next track in patterns. - page: Set offset for browsing tracks, 8 per page. ## Patterns Each song has up to 64 patterns for each channel with up to 64 rows each to place notes. ## Controls Gamepad (SNES style): layout: L2 R2 L1 R1 Up X Left Right Y A Down B If connecting a PS controller, its buttons will be mapped to the same locations (Y will map to square for example), but with its own button glyphs. DPAD - Move cursor. DPAD + B - Modify values, left right -1 +1 and up down +12 -12. Up / Down + Y - Move notes / patterns. R1 - Playback current sequencer. Y + R1 - Playback with cursor follow. L1 - Remove / reset. X - Hold to show menu. Left / Right to switch view. Menu -> opens menu. A - Exit menu if open. ### Keyboard (Mac): Return - Toggle edit / note preview. Command + Return - Toggle playback with cursor follow. Backspace / DEL - remove note / reset value. Option - Hold to show menu, left / right to change view. Space - Toggle playback. Arrow keys - Move cursor around. Command - hold while using up down arrows to move notes and patterns vertically, left right to change playback octave Playback notes: z, s, x, d, c, v, g, b, h, n, j, m, comma, l, period q, 2, w, 3, e, r, 5, t, 6, y, 7, u, i, 9, o, 0, p ## Platform support Currently VLK Tracker is only released on iOS, but more platforms could be added depending on time and interest. ## Standalone player (WIP) The audio producing part of VLK Tracker could be made to work as a standalone player, allowing it to be embedded in other kinds of software, for example as the audio engine for a game. Music and sfx is made in VLK Tracker, and the game loads the bank and sends messages to VLK for which music and sfx sequencer indices to play back. The first part is to make a proof of concept. ## Legal Copyright (c) 2026 Harry Lundström