Music Workshop Guide

The Music Workshop is Crusty Studio's portable music editor. It is a four-lane tracker that writes songs against the generic CrustyBasic sound API rather than one machine's sound chip, so the same song can be built for every target Crusty Studio supports.

That portability is the point of it, and it is also its limit. The portable player carries notes, lanes, waveform shapes, and volumes; it does not reach into chip registers. When you want SID registers, filter design, or chip-model-specific composition, use the SID Music Workshop instead — see Help → SID Music Guide.

Before you begin

1. Open any project. The Music Workshop is offered for every target.
2. Choose Tools → Music Workshop.
3. Create a new song or open an existing .crustymusic.json project from the Explorer.
4. Save regularly. Save writes into the project's music/ folder.

A song is data plus a player. Saving the project stores the tune; Export player include writes the MUSIC_* routine your game includes and calls.

The editor at a glance

• Song order — the list of patterns in playing order. Add, duplicate, and reorder patterns here; the order determines what plays and when.
• Instruments — the patch list. Add instrument creates one, and selecting a cell in the pattern grid brings that cell's instrument into the patch panel.
• Song strip — song title, author, BPM, Speed, Rows per beat, and a loop switch. A new song starts at 125 BPM, speed 6, four rows per beat, looping on.
• Pattern grid — 32 rows by default, with the Lead, Bass, Harmony, and Rhythm lanes. Each cell holds a note, an instrument number, and an effect. Lanes can be enabled or disabled individually in the Mix tab.
• Transport — play and stop, plus a volume slider. The pattern that is playing is highlighted as it runs.
• Instrument tab — the patch: waveform, duty, gate length, ADSR, arpeggio, vibrato, tremolo, delay, and noise settings, with a preview button and an optional loop so you hear changes as you make them.
• Mix tab — lane enables and the voice budget warning.
• Target API tab — a read-only view of the player source that will be exported.

Step by step

1. Set the tempo and feel

Set BPM, Speed, and Rows per beat before entering notes. Speed is the number of ticks per row, so it changes how much time each row has; rows per beat changes where the beat markers fall and therefore how the grid reads rhythmically.

2. Build the instruments

Create one instrument per job rather than one per note: a bass, a lead, a chord or pulse part, and a noise hit is the usual starting set. Each instrument has:

• Waveform — triangle, pulse, saw, or noise, with duty for the pulse shape.
• Gate length — how long a note holds before it releases, as a percentage of the row.
• ADSR — attack, decay, sustain, and release, as four 0–1 values.
• Arpeggio — a short list of semitone offsets cycled within a note, which is how a single-lane chip part implies a chord.
• Vibrato — depth and speed.
• Tremolo — depth, for volume movement.
• Delay — a delay before the note starts, for a softer attack.
• Noise mode — for the noise waveform.

Use the instrument's preview to audition the patch, switch the loop on, and tune it by ear before writing a part with it.

3. Enter the notes

Type a note into a cell and set its instrument number. Blank clears the cell, and OFF stops a held note. The effect column takes a three-character code from the list below.

4. Arrange the song

Add patterns, copy one as a starting point for the next, and put them in the song order. Short, reused patterns are easier to keep musical than one long block.

5. Check the mix

The Mix tab warns when the arrangement asks for more voices than the target has. A portable song can use four lanes, but targets with fewer channels need channel sharing or muting: a two-channel machine has to alternate or drop lanes. Plan which lanes the target can actually play before the arrangement grows.

6. Preview

Press play to hear the song through system audio. The preview is a plain Web Audio approximation, so treat it as a sketch, not as the target's sound: pulses are played as square waves, the noise lane previews as a sawtooth, ADSR is rendered as gain ramps, and the effect column is not heard at all. It is good enough to check the tune, the arrangement, and the instrument balance.

7. Save and export

Save writes <name>.crustymusic.json into music/. Export player include writes a .cbi into src/ — by default named after the song with a -player suffix — using the same include-name and overwrite rules as the other workshops. The generated player contains:

• MUSIC_ROWS, MUSIC_SPEED, MUSIC_LOOP, and MUSIC_EVENT_COUNT,
• parallel event tables for row, voice, note, shape, and volume,
• MUSIC_INIT, MUSIC_STOP, MUSIC_APPLY, and MUSIC_TICK.

Include the file from your game source, call MUSIC_INIT during setup, and call MUSIC_TICK once per frame. Notes are emitted as NOTE_<n><octave> names and shapes as SOUND_SHAPE_TRIANGLE, SOUND_SHAPE_PULSE, SOUND_SHAPE_SAW, or SOUND_SHAPE_NOISE, which the target's CrustyBasic runtime resolves for its own hardware.

What reaches the player matters. Only the note, the lane, the waveform shape, and the volume are exported per event. The instrument's ADSR, gate length, duty, arpeggio, vibrato, and tremolo shape the preview and record your intent, but they are not written into the player, and the effect column is not exported at all. If a sound depends on an envelope or an effect, either bake that into the arrangement or plan to reproduce it in code.

Effects you can write in a row

Code	Meaning
Axy	Arpeggio between semitone offsets
Vxy	Vibrato depth and speed
Uxx / Dxx	Pitch slide up or down
Txx	Tempo change
Wxy	Pulse-width or waveform movement

The effect column is an authoring aid and a written record of intent in this workshop. It shapes the preview only in the sense that the instrument settings it refers to also shape the preview; the exported player does not read it.

Import

Source	What happens
.crustymusic.json	The native project format. Tempo, speed, rows per beat, and the pattern shape are restored.
MIDI (.mid, .midi)	Notes are quantised to sixteenth notes and at most 64 patterns are built. Lossy: track identity is discarded, notes are sorted into lanes by pitch, every instrument is replaced by one of four fixed patches, notes are clamped to a playable range, and looping is switched off. Only the 64-pattern clip is reported.
FamiTracker text (.txt)	2A03 pulse, triangle, and noise material is converted into portable lanes. Duty, a short arpeggio, and a pitch macro survive; other effects are mapped or dropped, and DPCM and expansion-chip data are discarded. The workshop's status message lists what needed approximating.

There is no ProTracker .mod import. A dropped .mod is stored in music/ and listed in the manifest, but it is not converted, and the editor cannot open it.

Across the platforms

Target	What the Music Workshop gives you
Every target	The same editor, the same four lanes, and the same portable player include.
NES	Four voices available (two pulse, triangle, noise), so a four-lane arrangement usually fits.
C64, C128, Plus/4	Three SID voices, so four lanes need sharing or muting — the Mix tab warns about it. For register-level work use the SID Music Workshop instead.
Other targets	Whatever the target's runtime provides for the generic sound API. Studio does not know the channel count, so treat the Mix warning as advisory and check on the machine.

The Target API tab's preview selector (Portable, NES, C64) changes the description card only. The generated code is identical for all three; it is the target's CrustyBasic runtime that maps the sound calls onto real hardware.

A song written here plays on any target that implements the API. Where a chip cannot do something the song asks for — a fourth voice on a three-voice machine, for example — the arrangement has to give something up.

Practical advice

• Write the bass and the rhythm first, then the lead, then harmony. Four lanes fill up quickly and the low end carries the tune.
• Keep effects and envelope movement for the parts that need them. A plain, readable baseline is easier to debug than a busy one.
• Reuse patterns. A two-bar phrase played four times sounds more deliberate than one eight-bar block, and it is easier to vary one copy.
• Use OFF to end held notes rather than writing a quiet note; it makes the phrasing auditable.
• Check the Mix tab before you invest in a four-lane arrangement for a three-voice machine.
• Keep the exported player and the project together, and re-export after changing the song: the include is generated data, not a live link.

Troubleshooting

The exported player sounds different from the preview

Expected. The preview applies instrument envelopes and ignores the effect column; the player carries only note, lane, shape, and volume. Re-check the part with the settings the player can actually reproduce, or move the movement into the arrangement.

The preview's noise lane sounds like a sawtooth

The portable preview has no noise generator, so it approximates the noise lane with a sawtooth. The exported player sends the noise shape to the target, which renders it properly.

A MIDI import lost my instruments and tracks

That is the documented behaviour of the MIDI import: it is a sketch importer. It keeps the notes and the rhythm, sorts them into lanes by pitch, and replaces every instrument. Expect to re-instrument the result.

The import reported that it dropped effects

The FamiTracker text import converts what maps cleanly onto the portable lanes and reports the rest. Read the status message: anything it could not map is listed, and some of it affects only one channel of the original.

My song asks for more voices than the target has

The Mix tab warns when the arrangement needs more channels than are available. Disable a lane, share it between parts, or accept that a target with fewer channels cannot play every lane at once.