from xm_writer import XmModule, XmPattern, XmNote, XmInstrument, write_xm

# Create pattern
pattern = XmPattern.empty(64, num_channels=4)
pattern.set_note(0, 0, XmNote.play("C-4", instrument=1, volume=64))

# Create module with embedded samples
module = XmModule(
    name="My Song",
    num_channels=4,
    default_speed=6,
    default_bpm=125,
    order_table=[0],
    restart_position=0,
    patterns=[pattern],
    instruments=[XmInstrument.for_zx("kick", kick_bytes)],
)

write_xm(module, "output.xm")

XmNote.play("C-4", instrument=1, volume=64)  # Note on
XmNote.off()                                  # Note off
note_from_name("C#4")                         # Name to value

pattern = XmPattern.empty(64, num_channels=4)
pattern.set_note(row, channel, note)

XmInstrument.for_zx("kick", sample_bytes)  # Convenience for 22050 Hz

# Full control:
XmInstrument(
    name="kick",
    sample_data=kick_bytes,   # 16-bit signed PCM
    sample_rate=22050,        # Auto-calculates pitch correction
    sample_loop_type=0,       # 0=one-shot, 1=forward, 2=ping-pong
)

XmModule(
    name="Song Name",
    num_channels=4,           # 1-32
    default_speed=6,          # Ticks per row
    default_bpm=125,          # Tempo
    restart_position=0,       # Loop point in order table
    order_table=[0, 1, 0, 2], # Pattern sequence
    patterns=[...],
    instruments=[...],
)

# Recommended: Use convenience constructor
XmInstrument.for_zx("kick", data)

# Or set sample_rate:
XmInstrument(name="kick", sample_rate=22050, sample_data=data)

from xm_writer import validate_xm
validate_xm("output.xm")  # Raises ValueError if invalid

[[assets.trackers]]
id = "boss_theme"
path = "music/boss_theme.xm"

let music = rom_tracker(b"boss_theme", 10);
music_play(music, 0.8, 1);

project/
├── .studio/parsers/
│   ├── xm_writer.py     # Downloaded via /init-procgen
│   └── xm_types.py
├── .studio/specs/music/
│   └── song_name.spec.py
└── generated/music/
    └── song_name.xm     # Output (gitignored)