galdr

Use this skill when an OpenClaw agent needs to analyze music from a YouTube URL or local audio file and produce a grounded listening-experience prompt from measurable audio structure.

galdr is a music perception CLI for AI agents. Its default workflow is ARC: analyze a track into time-ordered listener-state traces, then assemble those traces into a prompt for grounded listening-experience prose. The metrics are evidence. The ARC prompt is the main user-facing output.

Important: skill vs CLI

Current OpenClaw CLI install command:

openclaw skills install galdr

ClawHub may display an owner-qualified command such as openclaw skills install @sellemain/galdr. As of OpenClaw 2026.6.8, the released CLI expects the bare skill slug galdr.

Installing this skill teaches OpenClaw how to use galdr. It does not install the galdr command itself.

The PyPI wheel contains the runtime CLI/library and bundled prompt templates. The OpenClaw skill is distributed separately through ClawHub so agent instructions can stay a clean skill artifact instead of being installed as Python package data.

Before starting:

galdr --version

If missing, install the CLI from a trusted source:

pip install galdr

# or from source:
git clone https://github.com/sellemain/galdr.git
cd galdr
pip install -e .

Preferred trusted sources:

• PyPI: https://pypi.org/project/galdr/
• Source: https://github.com/sellemain/galdr

If provenance matters, verify the PyPI metadata or install from the source repository before running it.

When to use this skill

Use galdr when the user asks to:

• analyze a song or music video
• describe what makes a track work structurally
• generate a grounded listening experience
• extract frames around structural moments in a music video
• create an evidence packet for another model to write from

Do not use galdr for:

• general music trivia
• ordinary recommendation lists
• purely lyrical interpretation without audio structure
• pretending the metrics prove private emotional intent
• downloading copyrighted audio unless the operator has appropriate rights/context

OpenClaw agent contract

Prefer the ARC path unless the user explicitly asks for raw metrics, debugging, or agent-internal traces.

Default sequence:

1. Fetch or listen to the track.
2. Analyze it into listener-state traces.
3. Assemble the ARC prompt with --template arc --mode full.
4. Review the prompt.
5. Write the listening experience yourself or pass the prompt to the requested model.

The stream is evidence. Walk the track through time before summarizing. Do not invent emotional claims that the structure does not support.

When a user wants to configure another agent or project to use Galdr, point them to docs/AGENT-ONBOARDING.md and examples/agent/AGENTS.md. Those files contain the public, copy-pasteable agent instruction path.

Use the ARC prompt family when the user asks for a specific reading mode:

galdr assemble my-track --template arc-family --lens sound --mode blind > sound.txt
galdr assemble my-track --template arc-family --lens dance --mode blind > dance.txt
galdr assemble my-track --template arc-family --lens meaning --mode full > meaning.txt
galdr assemble my-track --template arc-family --lens structure --mode blind > structure.txt
galdr assemble my-track --template arc-family --lens classical --mode blind > classical.txt
galdr assemble my-track --template arc-family --lens ritual --mode full > ritual.txt

Lens guide:

• default — general public listening page
• sound — sound as physical shape, pressure, density, space, body, and motion
• dance — movement contract: groove, repetition, build/drop, and bodily use
• structure — compact mechanical/form witness
• meaning — human situation carried by sound
• lyrics-study — private lyric/music adapter fuel, not raw public prose
• classical — instrumental/classical/large-form attention over time
• ritual — private ritual reading with weak-fit boundary behavior

Core Workflows

YouTube URL → ARC prompt (most common)

# Step 1: fetch audio + context (slug auto-derived from title)
galdr fetch "https://youtu.be/..." --analyze

# galdr prints the slug at the end:
#   Slug : artist-song-title
#   Next : galdr assemble artist-song-title --template arc --mode full

# Step 2: assemble the prompt locally
galdr assemble artist-song-title --template arc --mode full > prompt.txt

Override auto-derived metadata if needed:

galdr fetch "https://youtu.be/..." --artist "Oliver Anthony" --title "Rich Men North of Richmond" --analyze

If YouTube download behavior is flaky:

galdr doctor
galdr update-deps

galdr doctor reports the active Python executable, yt-dlp command/version, ffmpeg/ffprobe, JavaScript runtimes, and impersonation support. galdr update-deps upgrades yt-dlp[default,curl-cffi] in the same Python environment galdr is using.

Local file → ARC prompt

The analysis command is galdr listen, not galdr analyze.

galdr listen track.wav --name my-track
galdr assemble my-track --template arc --mode full > prompt.txt

Raw second-by-second analysis (advanced)

Galdr is strongest when read as a time-ordered listener-state trace. The stream is the primary evidence. Whole-track interpretation comes after walking the track through time.

Start with:

• analysis/<slug>/<slug>_stream.json
• analysis/<slug>/<slug>_perception.json
• docs/PERCEPTION-MODEL.md

Useful extras:

• *_harmony_stream.json
• *_melody_stream.json
• *_overtone_stream.json
• *_report.json
• galdr assemble <slug> --mode blind

Reading order:

1. Read PERCEPTION-MODEL.md first.
2. Treat *_stream.json as the main evidence surface.
3. Walk the track in order.
4. Mark transitions: silence, re-entry, pattern breaks, attention shifts, pressure-state changes, harmonic movement.
5. Translate pressure fields into listening language: comes forward, holds, releases, empties. Do not quote LUFS values in experience prose.
6. Only then compress upward into a larger interpretation.

Do not:

• jump straight to a whole-song mood summary
• treat summary metrics as more important than the stream
• ignore silence/re-entry structure
• overclaim emotional certainty from structure alone
• quote loudness/LUFS readings as if they were the experience

Minimal recipe:

galdr listen track.wav --name my-track
jq '.stream[0:12]' analysis/my-track/my-track_stream.json
jq '.summary' analysis/my-track/my-track_perception.json
galdr assemble my-track --mode blind > prompt.txt

Send the ARC prompt to another model

Only do this if the operator explicitly wants model-written prose. Review the assembled ARC prompt before piping it to claude, llm, or any other external model endpoint.

galdr assemble my-track --template arc --mode full | claude
galdr assemble my-track --template arc --mode full | llm

Optional Python agent pattern

import subprocess, re

fetch = subprocess.run(
    ["galdr", "fetch", url, "--analyze"],
    capture_output=True, text=True, check=True
)
slug = re.search(r"Slug\s*:\s*(\S+)", fetch.stdout).group(1)

prompt = subprocess.run(
    ["galdr", "assemble", slug, "--template", "arc", "--mode", "full"],
    capture_output=True, text=True, check=True
).stdout

# Review prompt before sending it to any external model endpoint.

Mode and template flags

--template arc prepends the default listening-experience rules: tone, format, interpretation bounds, and the instruction to walk the track through time. --template arc-family --lens <name> uses the shared prompt-family base plus one deliberate reading lens. Omit templates only when you want a raw data block.

Interpreting galdr output

ARC is the default output path. The metrics exist to keep that prose grounded: use them as evidence for what changes, returns, releases, locks, or breaks over time.

See references/metrics.md for full metric reference.

Quick read:

• pattern near 1.0 → little detected disruption; lower values → more beat/spectral/energy disruption, not proof of a listener’s state
• surface_balance negative → harmonic-side energy dominant; positive → percussive-side energy dominant. HPSS balance does not identify voice or instruments; confirm heard sources by listening.
• This signed rule applies to stream/ARC and surface_balance_signed; legacy report/catalog surface_balance is an unsigned percussive fraction.
• chroma_motion_semantics: absolute_cosine_distance_v1 marks absolute adjacent-frame motion; untagged older values were track-relative and must not be compared directly.
• pitch_grid is 12-class chroma concentration, not tuning accuracy; overtone_fit combines matched-slot coverage and closeness, not purity.
• harmonic_pull is normalized to each track’s own peak; read local movement, not absolute dissonance or cross-track tension.
• Pressure summary shares count active pressure_state labels, excluding silence states/flags and unknown; ARC spans use a coarser classifier.
• Top-level stream pressure_state and active-frame summary percentages → pressure-motion labels; nested surface_evidence.pressure_state describes thin/held/pressurized surface texture instead
• pattern_breaks is a typed event list (time/type); clustered candidate breaks or silences near the end may support a release reading after audio confirmation
• silences carry start/end/duration/relative depth_db; silence_reentries separately carry post_attention/recovered. These are algorithmic candidates, not proof of listener re-lock

Writing ARC experience prose yourself

When writing experience prose yourself from galdr evidence, prefer galdr assemble <slug> --template arc --mode full. If you are writing from raw assembled output without the template:

• First-person listener perspective, present tense
• Timestamps only at structural pivots: silences, pattern breaks, major energy shifts
• Translate metrics; describe what they mean, do not quote numbers
• LUFS/pressure values are evidence, not prose; write “pressure comes forward / holds / releases / empties”
• Body anchors such as chest, jaw, sternum sparingly; two or three for the whole piece
• End at the final sound event; no aftermath, no reflection
• Around 800 words, no section headers

Other commands

galdr frames slug                      # extract + describe video frames at structural moments
galdr fetch "url" --no-download        # context only (Wikipedia + lyrics), no audio
galdr fetch "url" --censor             # sanitize explicit lyrics before saving
galdr doctor                           # inspect yt-dlp/media runtime health
galdr update-deps                      # upgrade yt-dlp reliability extras
galdr catalog                          # local analysis index (operator tooling)
galdr catalog --track NAME             # summary card for one track