Pocket Chordsmith Godot Addon

Pocket Chordsmith imports web-app JSON into compiled Godot resources, then drives runtime music callbacks through one lightweight conductor node.

Author charts in the Pocket Chordsmith web app:

Pocket Chordsmith on itch.io

Pipeline

Pocket Chordsmith JSON
→ importer / schema migrator
→ PCSChartResource
→ PocketChordsmithConductor

Runtime Rules

• Gameplay uses PCSChartResource, not the full JSON.
• PocketChordsmithConductor owns:
  • timing
  • arrangement position
  • event cursors
  • beat, bar and section signals
  • markers
  • accents
  • transition requests
• Godot’s built-in audio system remains the playback foundation.
• Use:
  • buses
  • effects
  • AudioStreamPlayer
  • AudioStreamSynchronized for stems
  • AudioStreamPolyphonic for short accents and stingers

Editor Workflow

1. Enable the Pocket Chordsmith addon.
2. Open the Chordsmith main screen.
3. Import a Pocket Chordsmith JSON, paste raw JSON, or paste a PCS1: share code.
4. Inspect the import report, sequence, sections, timeline and event counts.
5. Optional: click Generate Web Sound Kit to create Pocket Chordsmith-style drum/stinger WAVs and a HYBRID playback profile.
6. Save the compiled chart as .tres or .res.
7. Assign the chart and playback profile to PocketChordsmithConductor in a level or demo scene.

Audio Notes

The addon does not require users to bring their own drum WAVs just to get started. The editor can generate a small built-in preview kit.

At runtime, audio still uses Godot-native AudioStream playback.

For a shipped game, use one of the following approaches:

• generated samples
• your own licensed drum/stinger samples
• rendered stems
• a mix of stems plus event-triggered samples

Visual track building stays in the web app for now. Godot receives the exported JSON or share code, compiles it to a lightweight PCSChartResource, then uses the conductor for timing, states, markers, cues and Godot-native audio routing.

A future Godot visual editor should build on the compiled chart and section data instead of porting the whole browser app into runtime.

Batch Migration

Use the editor Compile Folder button, or run the headless compiler:

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

Recommended Audio Buses

The main screen includes Create Chordsmith Audio Buses.

This safely adds missing recommended buses only:

Master
  Music_Master
    Music_Drums
    Music_Bass
    Music_Chords
    Music_Guitar
    Music_Melody
    Music_Stingers
    Music_FX
  SFX
  UI

Existing buses are reused. Existing sends are reported as warnings instead of being overwritten.

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 Audio Extension Points

Native audio extension points live in PCSPlaybackProfile and the conductor.

Supported extension points include:

• stem paths and bus names
• music/accent bus names
• intensity mix targets
• ducking rules
• filter automation maps
• optional native audio router node via native_audio_router_path

Playback Backends

STEM_SYNC

Preferred shipped-game path using rendered stems and Godot playback.

HYBRID

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

PROCEDURAL_PREVIEW

Editor-oriented preview mode. This is not the default mobile runtime path.

Adaptive Music States

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")

States are stored on PCSChartResource.music_states.

They can map to:

• section
• sequence
• loop sections
• entry
• stinger
• then return to

Transitions can wait for:

• immediate
• beat
• bar
• section
• loop
• marker boundaries

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)

Documentation

More documentation is included in the addon:

• CHANGELOG.md
• MIGRATION.md
• docs/GETTING_STARTED.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/UID_CACHE_RECOVERY.md
• SKILL.md for AI-assisted project integration