Pocket Chordsmith Godot Addon

Pocket Chordsmith for Godot imports Pocket Chordsmith JSON and PCS1: share codes into lightweight compiled Godot chart resources, then drives beat, bar, section, marker, cue, accent, stinger and adaptive music callbacks through one conductor node.

Author music in the Pocket Chordsmith web app, then bring it into Godot as game-ready musical structure.

Pocket Chordsmith on itch.io

Core Pipeline

Pocket Chordsmith JSON / PCS1 share code
→ importer / schema migrator
→ PCSChartResource
→ PCSPlaybackProfile
→ PocketChordsmithConductor
→ Godot-native audio, buses, effects and gameplay signals

Pocket Chordsmith data is treated as chart and score data, not as a full runtime browser synth. Godot receives the musical timing, section structure, events, markers, states and metadata, then uses Godot-native audio systems for actual playback.

Recommended Workflow

1. Write a song in Pocket Chordsmith.
2. Export JSON, copy a PCS1: share code, or use Push to Godot from the browser app.
3. In Godot, enable the Pocket Chordsmith addon.
4. Open the Chordsmith editor tab.
5. Import JSON, paste a share code, receive a pushed song, or import a Pocket DAW Godot Adaptive Pack.
6. Inspect the import report, timeline, sections, sequence and event counts.
7. Save the compiled chart as .tres or .res.
8. Assign the chart and playback profile to PocketChordsmithConductor in a level, music manager or demo scene.

Pocket DAW Godot Adaptive Packs

For stronger shipped-game audio, export a Godot Adaptive Pack from Pocket DAW and import it through the Godot addon.

The addon can extract the pack, compile the embedded Pocket Chordsmith source, and create a playback profile pointing to rendered full mixes, stems and section loops.

This is the preferred route when the final game should sound close to the arranged or mixed song rather than relying on preview samples.

Audio Paths

STEM_SYNC

Preferred shipped-game path. Uses prepared stems and section loops through Godot-native audio streams and buses.

HYBRID

Uses stems for the main music bed plus event-triggered accents, samples or stingers.

PROCEDURAL_PREVIEW

Editor and development preview path for auditioning imported charts before final stems exist. It is useful for testing, but not intended to replace production stems in shipped games.

Preview Audio

The addon includes a small built-in web-style preview kit so users can get started without bringing their own samples.

For text-only Pocket Chordsmith imports, Render Preview Audio can bake visible WAV preview stems for drums, bass, chords, guitar and melody. These preview stems route through Godot’s usual music buses so developers can adjust levels and effects in the mixer.

For final release audio, use Pocket DAW rendered packs, licensed samples, your own stems, or a hybrid setup.

Direct Push From Pocket Chordsmith

When the addon is enabled in an open Godot editor, Pocket Chordsmith can push a song directly to the local Godot receiver.

If the browser blocks local push, the app falls back to copying the same PCS1: code for manual paste into the Chordsmith tab.

Runtime Rules

• Gameplay should use PCSChartResource, not the full exported JSON.
• PocketChordsmithConductor owns timing, section position, event cursors, beat/bar/section signals, markers, accents, stingers and transition requests.
• Godot’s built-in audio system remains the playback foundation.
• Use Godot buses, effects, AudioStreamPlayer, AudioStreamSynchronized and AudioStreamPolyphonic for real runtime playback.
• Expensive audio rendering should happen before gameplay, not during the level runtime.

Adaptive Music

The conductor supports state changes and queued musical transitions.

conductor.set_music_state("exploration")

conductor.queue_music_state(
    "combat",
    PocketChordsmithConductor.TransitionBoundary.NEXT_BAR
)

conductor.queue_sequence(
    ["A", "B", "C"],
    PocketChordsmithConductor.TransitionBoundary.NEXT_SECTION
)

conductor.trigger_stinger("victory_hit", "exploration")

Transitions can wait for immediate, beat, bar, section, loop or marker boundaries.

Runtime Signal Example

@onready var conductor: PocketChordsmithConductor = $PocketChordsmithConductor

func _ready() -> void:
    conductor.accent_hit.connect(_on_accent)
    conductor.section_started.connect(_on_section_started)
    conductor.marker_hit.connect(_on_marker_hit)
    conductor.play()

Native Mix Controls

conductor.set_layer_volume("drums", -6.0)
conductor.mute_layer("melody", true)
conductor.duck_music(true, 0.5)
conductor.lowpass_music(0.75)
conductor.set_bus_effect_amount("Music_Master", "reverb", 0.25)

Recommended Audio Buses

The addon can create a recommended bus layout without overwriting existing project buses:

Master
  Music_Master
    Music_Drums
    Music_Bass
    Music_Chords
    Music_Guitar
    Music_Melody
    Music_Stingers
    Music_FX
      Music_Texture
  SFX
  UI

Buses are dry by default so developers can tune volume, EQ, reverb, compression, ambience and game-specific effects inside Godot’s native mixer.

Lofi, Chip Tune and Heavy Metal Metadata

The importer preserves Pocket Chordsmith style and sound metadata so Godot projects can understand the musical intent of imported songs without parsing the full source JSON at runtime.

Supported metadata may include:

• audio profile
• preset family
• drum kit
• bass tone
• chord instrument
• melody instrument
• guitar tone
• texture settings
• section mood
• intended gameplay state
• intensity or arrangement role

This is useful for lofi/chill, chip tune, heavy metal and other style-based projects where the same chart data may drive different gameplay states, menus, combat layers, boss sections, victory stingers or ambient background music.

Compiled PCSChartResource files keep this metadata available for runtime systems, editor tools and adaptive music workflows.

Headless Tools

Batch compile charts:

godot --headless --path <project> --script res://addons/pocket_chordsmith/tools/compile_pocket_chordsmith_charts.gd -- --source <json-or-folder> --beside-source

Import a Pocket DAW Godot Adaptive Pack:

godot --headless --path <project> --script res://addons/pocket_chordsmith/tools/import_daw_game_pack.gd -- --pack <pack.zip>

Render preview audio for a compiled chart/profile:

godot --headless --path <project> --script res://addons/pocket_chordsmith/tools/render_pocket_chordsmith_preview_audio.gd -- --chart <chart.tres> --profile <profile.tres>

Validate runtime chart/profile setup:

godot --headless --path <project> --script res://addons/pocket_chordsmith/tools/validate_pocket_chordsmith_runtime.gd -- --chart <chart.tres> --profile <profile.tres>

Documentation

More documentation is included in the addon:

• CHANGELOG.md
• MIGRATION.md
• docs/GETTING_STARTED.md
• docs/HEADLESS_VALIDATION.md
• docs/LEVEL_INTEGRATION.md
• docs/SHIPPING_CHECKLIST.md
• docs/RELEASE_CANDIDATE.md
• docs/CLI_COMPILE.md
• docs/RUNTIME_BRIDGE.md
• docs/STEM_WORKFLOW.md
• docs/SAMPLE_PREVIEW.md
• docs/PERFORMANT_AUDIO_ROADMAP.md
• docs/VISUAL_EDITOR_EXPLORATION.md
• docs/UID_CACHE_RECOVERY.md
• SKILL.md for AI-assisted project integration

Current Direction

Pocket Chordsmith is the music sketchpad.

Pocket DAW is the production and stem-rendering path.

The Godot addon is the game-integration layer: it receives musical intelligence, prepared audio assets, timing data and adaptive state information, then lets Godot handle playback, buses, effects and runtime performance.