Claude Skill

daw-cli

Instructs agents to control Stratawright DAW via the daw-cli command-line IPC interface. Covers session state, transport, track management, gain staging, VST3/AU plugin hosting, signal routing, clips, MIDI timeline editing, and non-visual DSP analysis & audio intelligence. Requir

LLM Mart · 0 points · 10 views 75 listing impressions 0 install-command copies
Download Goldwaterfung-Stratawright-skills_daw-cli-35008ae.zip · 14 KB

Install

skills CLI npx skills add https://github.com/Goldwaterfung/Stratawright/tree/master/skills/daw-cli
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install goldwaterfung-stratawright@llmmart
Git git clone https://github.com/Goldwaterfung/Stratawright.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole goldwaterfung/stratawright collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Stratawright DAW CLI Control

Overview

daw-cli is the command-line IPC client for Stratawright DAW, allowing AI agents and automation tools to query and mutate session state, manage tracks, perform gain-staging, host VST3/AU/CLAP plugins, configure signal routing & bus topology, execute clip and MIDI timeline edits, and perform non-visual DSP analysis & audio intelligence in real time.

All commands communicate with the running DAW application using a UNIX domain socket.

Binary location (if not installed on system PATH):

  • Quoted path: "./build/release/src/Agentic\ layer/daw-cli" (Release build)
  • Quoted path: "./build/debug/src/Agentic\ layer/daw-cli" (Debug build)
  • Standard executable name (if symlinked / on PATH): daw-cli

References Directory

  • error_codes.md: Detailed IPC error codes, trigger causes, and recovery actions.
  • command_schema.json: Machine-readable JSON schema defining all verbs, subcommands, flags, types, and defaults.

Prerequisites

  1. DAW Application Must Be Running: The GUI/Server application must be active before running daw-cli.
  2. UNIX Socket Path: The server listens on /tmp/daw_session.sock.
  3. Connectivity Check: Always verify connection state first before executing batch commands:
    daw-cli status
    
    If the DAW is not running, daw-cli will fail immediately with exit code 71 (DAW_NOT_RUNNING).

Output Formats & Parsing

By default, queries return TSV (Tab-Separated Values) for list commands and KV (Key-Value) for single-entity or status commands.

Agents can explicitly request machine-parsable formats using the --format flag:

daw-cli track list --format json

Supported formats:

  • --format json: Compact JSON string (Recommended for programmatic parsing).
  • --format tsv: Tab-Separated Values with header line (Default for lists).
  • --format kv: Key: Value line pairs (Default for inspect/status).
  • --format pretty: Human-readable structured block output.

Error Code Reference

When a command fails, daw-cli writes to stderr formatted as: ERROR <code> <SYMBOL> "<message>" and exits with the corresponding code.

Exit Code Symbol Cause Recommended Agent Recovery
0 OK Command completed cleanly Proceed to next step
70 INVALID_ARGS Missing required flag, bad value format, or unknown subcommand Check command syntax, required flags, and numeric value types
71 DAW_NOT_RUNNING Cannot connect to /tmp/daw_session.sock Prompt user to start Stratawright DAW
72 ENTITY_NOT_FOUND Track ID, plugin name, clip, or slot index missing Run track list or plugin list to verify exact identifiers
73 ENGINE_PLAYING_LOCKED Attempted structural edit restricted during playback Stop transport (daw-cli transport stop) before mutating topology
74 RESOURCE_BUSY_USER_TOUCH Destination slot is occupied or user is dragging control Add --overwrite flag for plugin slots or retry after user edit
75 PLUGIN_FAULT VST3/AU parameter out of bounds (0.0..1.0) or host crash Verify normalized parameter ranges
76 ASSET_I_O_ERROR Audio clip path unreadable or invalid file format Check file path existence and audio file permissions

Track Range Syntax

Commands accepting track parameters (--track, --tracks, --to-tracks) support integer ranges and comma-separated lists:

  • Single track: --track 1
  • Contiguous range: --track 1..4 (expands to tracks 1, 2, 3, 4)
  • Multi-range / list: --track 1..4,7..10 (expands to 1, 2, 3, 4, 7, 8, 9, 10)

Command Reference

1. Session State & Transport

Status Query

Returns current playback status, tempo, time signature, and playhead position.

daw-cli status
  • Success Symbol: STATUS_OK
  • Output Fields: TRANSPORT_STATE, TEMPO, TIME_SIGNATURE, POSITION_BARS, POSITION_SECONDS

Start Playback

daw-cli transport play
  • Success Symbol: PLAYBACK_STARTED

Stop Playback

daw-cli transport stop
  • Success Symbol: PLAYBACK_STOPPED

Set Tempo

daw-cli transport set-tempo --bpm 128.0
  • Success Symbol: TEMPO_UPDATED
  • Options: --bpm <float> (or --tempo <float>)

Set Time Signature

daw-cli transport set-time-signature --num 4 --den 4
  • Success Symbol: TIME_SIGNATURE_UPDATED
  • Options: --num <int>, --den <int>

2. Tracks & Gain-Staging

Create Track

daw-cli track create --name "Vocal Lead" --type audio --color yellow
  • Success Symbol: TRACK_CREATED
  • Options:
    • --name "<string>" (Default: "Untitled Track")
    • --type audio|midi|instrument|aux|folder (Default: "audio")
    • --color <red|blue|green|yellow|purple|orange|cyan|pink|white|grey|black|#HEX>

Create Tracks in Batch

daw-cli track create-batch --names "Kick,Snare,HH,Tom" --type audio
  • Success Symbol: BATCH_TRACKS_CREATED
  • Options: --names "<comma_separated_list>", --type audio|midi|instrument|aux|folder

List All Tracks

daw-cli track list [--format json]
  • Success Symbol: TRACK_LIST

Inspect Track Details

daw-cli track inspect --track 1
  • Success Symbol: TRACK_INSPECT

Set Track Gain (dB)

daw-cli track set-gain --track 1..4 --db -3.5
  • Success Symbol: TRACK_GAIN_UPDATED
  • Options: --track <range>, --db <float_in_dB>

Set Track Pan Position

daw-cli track set-pan --track 1 --value -0.25
  • Success Symbol: TRACK_PAN_UPDATED
  • Options: --track <range>, --value <float> (-1.0 Left to +1.0 Right)

Mute / Unmute Track

daw-cli track set-mute --track 2 --on
  • Success Symbol: TRACK_MUTE_UPDATED
  • Options: --track <range>, --on (omit --on to unmute)

Solo / Unsolo Track

daw-cli track set-solo --track 2 --on
  • Success Symbol: TRACK_SOLO_UPDATED
  • Options: --track <range>, --on (omit --on to unsolo)

Delete Tracks

daw-cli track delete --track 4
  • Success Symbol: TRACK_DELETED
  • Options: --track <range>

Set Track Color

daw-cli track set-color --track 1..4 --color red
  • Success Symbol: TRACK_COLOR_UPDATED

Auto-Color Tracks

Assigns semantic color palette based on instrument track names (e.g., Drums -> Red, Bass -> Purple, Vocals -> Yellow).

daw-cli track auto-color
  • Success Symbol: TRACKS_AUTO_COLORED

Sanitize Track Names

Trims whitespace, removes extensions (.wav, .mp3), and converts underscores to spaces across all tracks.

daw-cli track sanitize-names
  • Success Symbol: TRACK_NAMES_SANITIZED

3. Plugin Management

Scan Plugin Library

Triggers host scanner for installed VST3/AU plugins.

daw-cli plugin scan
  • Success Symbol: PLUGIN_SCAN_COMPLETED

List Discovered Plugins

daw-cli plugin list --filter "FabFilter" --category effect --head 10 --format json
  • Success Symbol: PLUGIN_LIST
  • Options:
    • --filter "<substring>": Case-insensitive search on name or vendor.
    • --category effect|instrument (or fx, synth).
    • --head <int> / --tail <int>: Limit output row count.

Add Plugin to Track Slot

daw-cli plugin add --track 1 --name "FabFilter Pro-Q 3" --slot 0
  • Success Symbol: PLUGIN_ADDED
  • Options:
    • --track <range>
    • --name "<exact_name>" (Must match exact case returned by plugin list) or --id <uint32>
    • --slot <0..7> (Default: 0)

Set Plugin Parameter Value

daw-cli plugin set-param --track 1 --plugin 0 --param 3 --val 0.75
  • Success Symbol: PLUGIN_PARAM_UPDATED
  • Options:
    • --track <uint32>
    • --plugin <slot_0..7> (or --slot)
    • --param <param_index>
    • --val <float_0.0_to_1.0> (Normalized range)

Copy Single Plugin to Other Tracks

daw-cli plugin copy --from-track 1 --slot 0 --to-tracks 2..5 --overwrite
  • Success Symbol: PLUGIN_COPIED
  • Options:
    • --from-track <uint32>
    • --slot <0..7>
    • --to-tracks <range>
    • --overwrite: Required if target slots are already occupied.

Copy Entire Plugin Insert Chain

daw-cli plugin copy-chain --from-track 1 --to-tracks 2..5 --overwrite
  • Success Symbol: PLUGIN_CHAIN_COPIED
  • Options:
    • --from-track <uint32>
    • --to-tracks <range>
    • --overwrite: Required if any target slot in 0..7 is occupied.

4. Session Preparation (prep)

Gain-Stage Track Headroom

Adjusts track fader gains to achieve requested target RMS headroom.

daw-cli prep gain-stage --track 1..8 --target-rms -18.0
  • Success Symbol: GAIN_STAGE_COMPLETED
  • Options: --track <range>, --target-rms <float_dB> (Default: -18.0)

5. Clips & Timeline Editing (clip, midi)

Add Audio Clip

daw-cli clip add-audio --track 1 --path "/audio/vocal.wav" --start 1.1.0
  • Success Symbol: CLIP_ADDED
  • Options: --track <uint32>, --path "<string>", --start <BBT>

Add MIDI Clip

daw-cli clip add-midi --track 1 --start 1.1.0 --dur 4.0.0
  • Success Symbol: CLIP_ADDED
  • Options: --track <uint32>, --start <BBT>, --dur <BBT>

Add MIDI Note Event

daw-cli midi add-note --track 1 --clip 1 --pitch C4 --velocity 100 --start 1.1.0 --dur 1.0.0
  • Success Symbol: MIDI_NOTE_ADDED
  • Options: --track <uint32>, --clip <uint32>, --pitch <musical_note, e.g. C4, A5, Db5 or integer 0..127>, --velocity <0..127>, --start <BBT>, --dur <BBT>

List Arrangement Clips

daw-cli clip list --track 1 [--bar 1-8]
  • Success Symbol: CLIP_LIST
  • Options: --track <uint32>, --bar <start_bar-end_bar>

Set Clip Gain (dB)

daw-cli clip set-gain --track 1 --clip 1 --db -3.0
  • Success Symbol: CLIP_GAIN_UPDATED
  • Options: --track <uint32>, --clip <uint32>, --db <float>

Mute / Unmute Clip

daw-cli clip set-mute --track 1 --clip 1 --on true
  • Success Symbol: CLIP_MUTE_UPDATED
  • Options: --track <uint32>, --clip <uint32>, --on <true|false>

Split Clip

daw-cli clip split --track 1 --clip 1 --at 2.1.0
  • Success Symbol: CLIP_SPLIT
  • Options: --track <uint32>, --clip <uint32>, --at <BBT>

Trim Silence

daw-cli clip trim-silence --track 1 --clip 1 --threshold -48.0 --fade-ms 5.0
  • Success Symbol: CLIP_SILENCE_TRIMMED
  • Options: --track <uint32>, --clip <uint32>, --threshold <float_dB>, --fade-ms <float>

Quantize Clip / MIDI

daw-cli clip quantize --track 1 --clip 1 --grid 1/16 --strength 1.0
  • Success Symbol: MIDI_CLIPS_QUANTIZED / CLIPS_QUANTIZED
  • Options: --track <uint32>, --clip <uint32>, --grid <grid_fraction>, --strength <float_0..1>

Merge Clips

daw-cli clip merge --track 1 --start 1.1.0 --end 5.1.0
  • Success Symbol: CLIPS_MERGED
  • Options: --track <uint32>, --start <BBT>, --end <BBT>, --clips "<list>"

Move Clip

daw-cli clip move --track 1 --clip 1 --to-pos 3.1.0 [--to-track 2]
  • Success Symbol: CLIP_MOVED
  • Options: --track <uint32>, --clip <uint32>, --to-pos <BBT>, --to-track <uint32>

Nudge Clip Position

daw-cli clip nudge --track 1 --clip 1 --by +1/16
  • Success Symbol: CLIP_NUDGED
  • Options: --track <uint32>, --clip <uint32>, --by <+|-grid_fraction>

6. Signal Routing & Topology (route)

Route Tracks to Bus / Folder

Routes source track outputs to a destination bus or folder track, updating both audio routing and parent folder hierarchy.

daw-cli route folder --track 1..4 --to 10
  • Success Symbol: ROUTE_FOLDER_UPDATED
  • Options: --track <range>, --to <bus_track_id>

Add Aux Send

Configures a pre-fader or post-fader send from source tracks to a target Aux track with gain level in dB.

daw-cli route send --from 1..4 --to 14 --db -12.0 --tap post
  • Success Symbol: ROUTE_SEND_ADDED
  • Options: --from <range>, --to <aux_track_id>, --db <float_dB> (Default: -12.0), --tap pre|post (Default: post)

Set Up Sidechain Connection

Links a trigger source track as a sidechain input into a target track's plugin or instrument slot.

daw-cli route sidechain --source 1 --to-track 9 --slot 0 --db 0.0
  • Success Symbol: ROUTE_SIDECHAIN_LINKED
  • Options: --source <track_id>, --to-track <track_id>, --slot <0..7> (Default: 0), --db <float_dB> (Default: 0.0)

List Routing Topology

Lists signal routing connections, main outputs, sends, and sidechains across all tracks.

daw-cli route list [--format tsv|kv|json|pretty]
  • Success Symbol: ROUTE_LIST

7. Non-Visual DSP Analysis & Audio Intelligence (analyze)

Domain 6 provides a non-visual DSP analysis and audio intelligence suite across 9 specialized subcommands, supporting both Short Frame (real-time telemetry) and Full Track (offline decoded asset) processing.

Frequency Masking & Collision Detection

Calculates psychoacoustic masking overlap and energy density collisions across 24 critical Bark bands between two tracks using Schroeder spreading functions.

daw-cli analyze masking --track 1 --vs 2 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_MASKING
  • Options: --track <uint32>, --vs <uint32>
  • Output Fields: PRIMARY_TRACK, VS_TRACK, OVERALL_MASKING_INDEX (\(C_{A,B} \in [0.0, 1.0]\)), COLLISION_RISK (LOW_MASKING, MODERATE_MASKING, HIGH_MASKING), MASKED_BAND_COUNT, BAND_1_RANGE_HZ, BAND_1_MASK_AMOUNT_DB, BAND_1_RECOMMENDED_ACTION (SIDECHAIN_DUCK_PRIMARY_LOWS, CUT_VS_TRACK_EQ_<freq>HZ), ...

Narrow-Q Resonance Peak Detection

Scans track audio spectrum with a 31-bin moving median spectral envelope filter to isolate harsh narrow-Q resonances, pitch note names, and Q-factor sharpness (\(Q \ge 8.0\)).

daw-cli analyze resonance --track 1 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_RESONANCE
  • Options: --track <uint32>
  • Output Fields: TRACK_ID, TOTAL_RESONANCES_FOUND, RESONANCE_1_FREQ_HZ, RESONANCE_1_NOTE (e.g. E4, A5), RESONANCE_1_PROMINENCE_DB, RESONANCE_1_Q_FACTOR, RESONANCE_1_SEVERITY (HIGH_SEVERITY_SURGICAL_CUT, MODERATE), RESONANCE_1_REC_NOTCH_DB

Multi-Track Pearson Phase Correlation Matrix

Computes an \(N \times N\) pairwise Pearson correlation matrix (\(r_{i,j}\)) across a list or range of tracks to flag phase cancellation risks and identify destructive anti-phase pairs.

daw-cli analyze phase-matrix --track 1..4 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_PHASE_MATRIX
  • Options: --track <range|list> (e.g. 1..4, 1,2,3,4)
  • Output Fields: TRACKS_ANALYZED, GLOBAL_GROUP_HEALTH (HEALTHY_MONO_COMPATIBLE, WARNING_SEVERE_CANCELLATION), WORST_PAIR_1, WORST_CORRELATION_1, REC_ACTION_1 (FLIP_POLARITY_TRACK_<id>, NUDGE_DELAY_TRACK_<id>), CORRELATION_MATRIX_FLAT

Cross-Correlation Phase Alignment

Calculates cross-correlation lag across \([-128, +128]\) sample offsets to recommend sample-accurate and millisecond time shifts (\(\Delta t_{\text{ms}} = \frac{\text{offset}}{f_s} \times 1000\)).

daw-cli analyze phase-align --track 1 --vs 2 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_PHASE_ALIGN
  • Options: --track <uint32>, --vs <uint32>
  • Output Fields: PRIMARY_TRACK, VS_TRACK, RECOMMENDED_SAMPLE_OFFSET, RECOMMENDED_TIME_OFFSET_MS, CURRENT_CORRELATION, IMPROVED_CORRELATION, RECOMMENDED_ACTION (e.g. NUDGE_REGION_TRACK_2_BY_-48_SAMPLES)

Window Offline Telemetry

Performs offline telemetry analysis over a specified timeline range for momentary/short-term EBU R128 BS.1770 LUFS, true-peak dBTP, crest factor, and safety gain trim.

daw-cli analyze window --track 1 --start 1.1.0 --dur 4.0.0 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_WINDOW_STREAM
  • Options: --track <uint32>, --start <BBT>, --dur <BBT>
  • Output Fields: TRACK_ID, START_POS, DUR_POS, MOMENTARY_LUFS, SHORT_TERM_LUFS, SAMPLE_PEAK_DBFS, TRUE_PEAK_DBTP, IS_CLIPPING, CLIPPING_EVENTS_COUNT, CREST_FACTOR_DB, SPECTRAL_CENTROID_HZ, STEREO_CORRELATION, SAFETY_STATUS (SAFE_NORMAL, VIOLATION_DANGER_REDUCE_GAIN), REC_GAIN_TRIM_DB

7-Band Spectral Energy Balance

Evaluates acoustic energy distribution across 7 standardized bands (Sub: 20-60Hz, Bass: 60-250Hz, Low-Mid: 250-500Hz, Mid: 500-2kHz, High-Mid: 2-4kHz, Highs: 4-8kHz, Air: 8-20kHz) alongside spectral centroid, 85% energy rolloff frequency, and spectral tilt (dB/octave).

daw-cli analyze spectrum --track 1 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_SPECTRUM
  • Options: --track <uint32>
  • Output Fields: TRACK_ID, SPECTRAL_CENTROID_HZ, SPECTRAL_TILT_DB_OCT, SPECTRAL_ROLLOFF_HZ, SUB_BAND_DBFS, BASS_BAND_DBFS, LOW_MID_BAND_DBFS, MID_BAND_DBFS, HIGH_MID_BAND_DBFS, HIGHS_BAND_DBFS, AIR_BAND_DBFS

EBU R128 Loudness Audit (Full Track / Real-Time)

Performs ITU-R BS.1770-4 / EBU R128 integrated loudness, loudness range (LRA), short-term/momentary peak LUFS, sample peak, and crest factor.

daw-cli analyze loudness --track 1 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_LOUDNESS
  • Options: --track <uint32>
  • Output Fields: TRACK_ID, INTEGRATED_LUFS, SHORT_TERM_MAX_LUFS, MOMENTARY_MAX_LUFS, LRA_LU, CREST_FACTOR_DB, SAMPLE_PEAK_DBFS, TRUE_PEAK_DBTP

True-Peak Inter-Sample Clipping Audit

Performs 4x oversampled true-peak analysis to detect inter-sample clipping events and safety margin status (\(0.0\text{ dBTP}\) threshold).

daw-cli analyze true-peak --track 1 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_TRUE_PEAK
  • Options: --track <uint32>
  • Output Fields: TRACK_ID, MAX_TRUE_PEAK_DBTP, TOTAL_CLIPPING_EVENTS, SAFETY_STATUS (SAFE_NORMAL, VIOLATION_DANGER)

Mid/Side Stereo Width Audit

Measures Mid RMS (\(0.5(L+R)\)), Side RMS (\(0.5(L-R)\)), Mid-to-Side ratio in dB, stereo width percentage, and mono fold-down cancellation loss in dB.

daw-cli analyze stereo-width --track 1 [--format json|tsv|kv|pretty]
  • Success Symbol: ANALYSIS_STEREO_WIDTH
  • Options: --track <uint32>
  • Output Fields: TRACK_ID, MID_RMS_DBFS, SIDE_RMS_DBFS, MS_RATIO_DB, STEREO_WIDTH_PCT, MONO_FOLD_LOSS_DB

8. Export & Asynchronous Render Jobs (export, job)

The export and job command suites allow agents to trigger offline full-mix bounces, export multi-track stems, and asynchronously query or cancel active rendering jobs.

8.1 Master Mixdown Export (export master)

Enqueues an offline bounce of the full master arrangement or loop selection.

daw-cli export master --output <path> [options]
  • Options:
    • --output, -o <path>: Destination audio file path (e.g. /tmp/mixdown.wav).
    • --format <wav|flac|mp3|aiff|ogg>: Audio codec (default: wav).
    • --bit-depth <16|24|32>: Sample precision (default: 24).
    • --sample-rate <uint>: Target sample rate in Hz (default: project sample rate).
    • --dither <on|off>: Psychoacoustic TPDF dither injection (default: on).
    • --split-planar <on|off>: Export split Left/Right planar files (default: off).
    • --normalize <on|off>: Enable peak normalization (default: off).
    • --norm-db <float>: Target peak in dBFS (e.g. -0.1).
    • --range <full|loop>: Render arrangement timeline or active loop region (default: loop if looping is enabled, else full).
    • --tail-ms <uint>: Reverb/decay tail in milliseconds for full arrangement bounces (default: 1000).
  • Success Symbol: EXPORT_JOB_STARTED
  • Output Fields: job_id, type, format, sample_rate, bit_depth, destination

8.2 Stem Export (export stems)

Enqueues multi-track stem exports across selected session tracks.

daw-cli export stems --output <directory> [options]
  • Options:
    • --output, -o <directory>: Target directory where stem files will be saved (e.g. /tmp/stems/).
    • --track <range|all>: Track index range (1..8, 1,2,5, or all).
    • --naming-pattern <pattern>: Filename pattern token (default: "{track_index:02d}_{track_name}", option: "{project}_{track_name}").
    • --format <wav|flac|mp3|aiff|ogg>: Codec (default: wav).
    • --bit-depth <16|24|32>: Sample bit depth (default: 24).
    • --sample-rate <uint>: Target sample rate (default: project sample rate).
    • --print-sends: Print auxiliary send returns into track stems (wet bounce).
    • --bypass-sidechain: Disable mixdown sidechain ducking during export (default: active).
    • --range <full|loop>: Bounds selection.
    • --tail-ms <uint>: Decay tail duration in milliseconds.
    • --normalize <on|off>: Stem peak normalization.
    • --norm-db <float>: Target peak in dBFS.
  • Success Symbol: STEM_EXPORT_STARTED
  • Output Fields: job_id, type, total_tracks, format, sample_rate, destination

8.3 Job Queue Management (job)

Listing Jobs

Lists all active, queued, and completed render jobs.

daw-cli job list [--format json|tsv|kv|pretty]
  • Success Symbol: JOB_LIST
  • Output Columns: JOB_ID, NAME, TYPE, STATUS, PROGRESS, OUTPUT

Querying Job Status

Queries real-time progress and status details for a specific job.

daw-cli job status --id <job_id> [--format json|tsv|kv|pretty]
  • Success Symbol: JOB_STATUS
  • Output Fields: job_id, name, type, status, progress, status_message, destination, current_track_index, total_tracks

Cancelling a Job

Aborts an in-progress or queued background render job.

daw-cli job cancel --id <job_id>
  • Success Symbol: JOB_CANCELLED
  • Output Fields: job_id

Common Workflows

Workflow A: Setting Up a 4-Track Drum Session

# 1. Verify DAW application connection
daw-cli status

# 2. Batch-create drum tracks
daw-cli track create-batch --names "Kick,Snare,HiHat,Tom" --type audio

# 3. Clean up track names and apply instrument colors
daw-cli track sanitize-names
daw-cli track auto-color

# 4. Gain stage all drum tracks to -18 dB RMS headroom
daw-cli prep gain-stage --track 1..4 --target-rms -18.0

Workflow B: Applying and Distributing an EQ Plugin Chain

# 1. Search for available EQ plugins
daw-cli plugin list --filter "EQ" --category effect --format json

# 2. Add EQ plugin to slot 0 of Vocal Lead (Track 1)
daw-cli plugin add --track 1 --name "FabFilter Pro-Q 3" --slot 0

# 3. Copy EQ plugin from Track 1 slot 0 to Backing Vocals (Tracks 2..5)
daw-cli plugin copy --from-track 1 --slot 0 --to-tracks 2..5 --overwrite

Workflow C: Submix Bus & Sidechain Setup

# 1. Route drum tracks 1..4 into Drums Bus (Track 10)
daw-cli route folder --track 1..4 --to 10

# 2. Add post-fader send from Snare (Track 2) to Reverb Aux (Track 14) at -12 dB
daw-cli route send --from 2 --to 14 --db -12.0 --tap post

# 3. Link Kick (Track 1) as sidechain trigger to Synth Bass (Track 9) slot 0
daw-cli route sidechain --source 1 --to-track 9 --slot 0 --db 0.0

# 4. Inspect session routing topology
daw-cli route list --format tsv

Workflow D: Acoustic Guitar & Vocal Masking Audit and Resonant Notch Fix

# 1. Analyze frequency masking between Vocal (Track 1) and Acoustic Guitar (Track 2)
daw-cli analyze masking --track 1 --vs 2

# 2. Detect harsh resonant peaks and Q-factors on Acoustic Guitar
daw-cli analyze resonance --track 2

# 3. Evaluate multi-mic phase alignment between Top Snare (Track 3) and Bottom Snare (Track 4)
daw-cli analyze phase-align --track 3 --vs 4

# 4. Perform offline windowed LUFS & True-Peak telemetry on Master Output (Track 10)
daw-cli analyze window --track 10 --start 1.1.0 --dur 4.0.0

Workflow E: Bouncing Master Mixdown and Exporting Stems

# 1. Export 24-bit 48kHz master mixdown with -0.1 dBFS normalization
daw-cli export master --output "/tmp/mixdown.wav" --format wav --bit-depth 24 --normalize on --norm-db -0.1

# 2. Export drum stems (tracks 1 to 4) to directory
daw-cli export stems --output "/tmp/stems/" --track 1..4 --format wav --bit-depth 24

# 3. Check active render jobs
daw-cli job list

# 4. Poll specific job status until completed
daw-cli job status --id 1

Common Mistakes

  1. Plugin Name Case Sensitivity: daw-cli plugin add --name requires an exact case-sensitive match. plugin add --name "fabfilter pro-q 3" will fail with 72 ENTITY_NOT_FOUND. Always run plugin list --filter "FabFilter" first to copy the exact name string.

  2. Forgetting --overwrite on Occupied Plugin Slots: Copying plugins (plugin copy or plugin copy-chain) to tracks with existing plugins in target slots without --overwrite will fail with error 74 RESOURCE_BUSY_USER_TOUCH.

  3. Not Checking status Before Issuing Commands: Attempting to execute commands when Stratawright is closed returns error 71 DAW_NOT_RUNNING. Always run daw-cli status first to confirm connectivity.

  4. Missing Comparison Target for Pairwise Analysis: Commands like daw-cli analyze masking and daw-cli analyze phase-align require --vs <target_track_id>. Omitting --vs returns error 70 INVALID_ARGS.

Files (stratawright)
  • references
    • command_schema.json 20.4 KB
      Loading…
    • error_codes.md 3 KB
      Loading…
  • SKILL.md 25.8 KB
    ---
    name: daw-cli
    description: >-
      Instructs agents to control Stratawright DAW via the daw-cli command-line
      IPC interface. Covers session state, transport, track management, gain
      staging, VST3/AU plugin hosting, signal routing, clips, MIDI timeline editing, and non-visual DSP analysis & audio intelligence. Requires the DAW application to be running.
    ---
    
    # Stratawright DAW CLI Control
    
    ## Overview
    
    `daw-cli` is the command-line IPC client for **Stratawright DAW**, allowing AI agents and automation tools to query and mutate session state, manage tracks, perform gain-staging, host VST3/AU/CLAP plugins, configure signal routing & bus topology, execute clip and MIDI timeline edits, and perform non-visual DSP analysis & audio intelligence in real time.
    
    All commands communicate with the running DAW application using a UNIX domain socket.
    
    Binary location (if not installed on system PATH):
    - Quoted path: `"./build/release/src/Agentic\ layer/daw-cli"` (Release build)
    - Quoted path: `"./build/debug/src/Agentic\ layer/daw-cli"` (Debug build)
    - Standard executable name (if symlinked / on PATH): `daw-cli`
    
    ## References Directory
    - [error_codes.md](file:///Users/goldenfung/Documents/agent-based-daw/skills/daw-cli/references/error_codes.md): Detailed IPC error codes, trigger causes, and recovery actions.
    - [command_schema.json](file:///Users/goldenfung/Documents/agent-based-daw/skills/daw-cli/references/command_schema.json): Machine-readable JSON schema defining all verbs, subcommands, flags, types, and defaults.
    
    ---
    
    ## Prerequisites
    
    1. **DAW Application Must Be Running**: The GUI/Server application must be active before running `daw-cli`.
    2. **UNIX Socket Path**: The server listens on `/tmp/daw_session.sock`.
    3. **Connectivity Check**: Always verify connection state first before executing batch commands:
       ```bash
       daw-cli status
       ```
       If the DAW is not running, `daw-cli` will fail immediately with exit code `71` (`DAW_NOT_RUNNING`).
    
    ---
    
    ## Output Formats & Parsing
    
    By default, queries return `TSV` (Tab-Separated Values) for list commands and `KV` (Key-Value) for single-entity or status commands.
    
    Agents can explicitly request machine-parsable formats using the `--format` flag:
    
    ```bash
    daw-cli track list --format json
    ```
    
    Supported formats:
    - `--format json`: Compact JSON string (Recommended for programmatic parsing).
    - `--format tsv`: Tab-Separated Values with header line (Default for lists).
    - `--format kv`: `Key: Value` line pairs (Default for inspect/status).
    - `--format pretty`: Human-readable structured block output.
    
    ---
    
    ## Error Code Reference
    
    When a command fails, `daw-cli` writes to `stderr` formatted as: `ERROR <code> <SYMBOL> "<message>"` and exits with the corresponding code.
    
    | Exit Code | Symbol | Cause | Recommended Agent Recovery |
    | :--- | :--- | :--- | :--- |
    | `0` | `OK` | Command completed cleanly | Proceed to next step |
    | `70` | `INVALID_ARGS` | Missing required flag, bad value format, or unknown subcommand | Check command syntax, required flags, and numeric value types |
    | `71` | `DAW_NOT_RUNNING` | Cannot connect to `/tmp/daw_session.sock` | Prompt user to start Stratawright DAW |
    | `72` | `ENTITY_NOT_FOUND` | Track ID, plugin name, clip, or slot index missing | Run `track list` or `plugin list` to verify exact identifiers |
    | `73` | `ENGINE_PLAYING_LOCKED` | Attempted structural edit restricted during playback | Stop transport (`daw-cli transport stop`) before mutating topology |
    | `74` | `RESOURCE_BUSY_USER_TOUCH` | Destination slot is occupied or user is dragging control | Add `--overwrite` flag for plugin slots or retry after user edit |
    | `75` | `PLUGIN_FAULT` | VST3/AU parameter out of bounds (`0.0`..`1.0`) or host crash | Verify normalized parameter ranges |
    | `76` | `ASSET_I_O_ERROR` | Audio clip path unreadable or invalid file format | Check file path existence and audio file permissions |
    
    ---
    
    ## Track Range Syntax
    
    Commands accepting track parameters (`--track`, `--tracks`, `--to-tracks`) support integer ranges and comma-separated lists:
    
    - Single track: `--track 1`
    - Contiguous range: `--track 1..4` (expands to tracks 1, 2, 3, 4)
    - Multi-range / list: `--track 1..4,7..10` (expands to 1, 2, 3, 4, 7, 8, 9, 10)
    
    ---
    
    ## Command Reference
    
    ### 1. Session State & Transport
    
    #### Status Query
    Returns current playback status, tempo, time signature, and playhead position.
    ```bash
    daw-cli status
    ```
    - **Success Symbol**: `STATUS_OK`
    - **Output Fields**: `TRANSPORT_STATE`, `TEMPO`, `TIME_SIGNATURE`, `POSITION_BARS`, `POSITION_SECONDS`
    
    #### Start Playback
    ```bash
    daw-cli transport play
    ```
    - **Success Symbol**: `PLAYBACK_STARTED`
    
    #### Stop Playback
    ```bash
    daw-cli transport stop
    ```
    - **Success Symbol**: `PLAYBACK_STOPPED`
    
    #### Set Tempo
    ```bash
    daw-cli transport set-tempo --bpm 128.0
    ```
    - **Success Symbol**: `TEMPO_UPDATED`
    - **Options**: `--bpm <float>` (or `--tempo <float>`)
    
    #### Set Time Signature
    ```bash
    daw-cli transport set-time-signature --num 4 --den 4
    ```
    - **Success Symbol**: `TIME_SIGNATURE_UPDATED`
    - **Options**: `--num <int>`, `--den <int>`
    
    ---
    
    ### 2. Tracks & Gain-Staging
    
    #### Create Track
    ```bash
    daw-cli track create --name "Vocal Lead" --type audio --color yellow
    ```
    - **Success Symbol**: `TRACK_CREATED`
    - **Options**:
      - `--name "<string>"` (Default: "Untitled Track")
      - `--type audio|midi|instrument|aux|folder` (Default: "audio")
      - `--color <red|blue|green|yellow|purple|orange|cyan|pink|white|grey|black|#HEX>`
    
    #### Create Tracks in Batch
    ```bash
    daw-cli track create-batch --names "Kick,Snare,HH,Tom" --type audio
    ```
    - **Success Symbol**: `BATCH_TRACKS_CREATED`
    - **Options**: `--names "<comma_separated_list>"`, `--type audio|midi|instrument|aux|folder`
    
    #### List All Tracks
    ```bash
    daw-cli track list [--format json]
    ```
    - **Success Symbol**: `TRACK_LIST`
    
    #### Inspect Track Details
    ```bash
    daw-cli track inspect --track 1
    ```
    - **Success Symbol**: `TRACK_INSPECT`
    
    #### Set Track Gain (dB)
    ```bash
    daw-cli track set-gain --track 1..4 --db -3.5
    ```
    - **Success Symbol**: `TRACK_GAIN_UPDATED`
    - **Options**: `--track <range>`, `--db <float_in_dB>`
    
    #### Set Track Pan Position
    ```bash
    daw-cli track set-pan --track 1 --value -0.25
    ```
    - **Success Symbol**: `TRACK_PAN_UPDATED`
    - **Options**: `--track <range>`, `--value <float>` (`-1.0` Left to `+1.0` Right)
    
    #### Mute / Unmute Track
    ```bash
    daw-cli track set-mute --track 2 --on
    ```
    - **Success Symbol**: `TRACK_MUTE_UPDATED`
    - **Options**: `--track <range>`, `--on` (omit `--on` to unmute)
    
    #### Solo / Unsolo Track
    ```bash
    daw-cli track set-solo --track 2 --on
    ```
    - **Success Symbol**: `TRACK_SOLO_UPDATED`
    - **Options**: `--track <range>`, `--on` (omit `--on` to unsolo)
    
    #### Delete Tracks
    ```bash
    daw-cli track delete --track 4
    ```
    - **Success Symbol**: `TRACK_DELETED`
    - **Options**: `--track <range>`
    
    #### Set Track Color
    ```bash
    daw-cli track set-color --track 1..4 --color red
    ```
    - **Success Symbol**: `TRACK_COLOR_UPDATED`
    
    #### Auto-Color Tracks
    Assigns semantic color palette based on instrument track names (e.g., Drums -> Red, Bass -> Purple, Vocals -> Yellow).
    ```bash
    daw-cli track auto-color
    ```
    - **Success Symbol**: `TRACKS_AUTO_COLORED`
    
    #### Sanitize Track Names
    Trims whitespace, removes extensions (`.wav`, `.mp3`), and converts underscores to spaces across all tracks.
    ```bash
    daw-cli track sanitize-names
    ```
    - **Success Symbol**: `TRACK_NAMES_SANITIZED`
    
    ---
    
    ### 3. Plugin Management
    
    #### Scan Plugin Library
    Triggers host scanner for installed VST3/AU plugins.
    ```bash
    daw-cli plugin scan
    ```
    - **Success Symbol**: `PLUGIN_SCAN_COMPLETED`
    
    #### List Discovered Plugins
    ```bash
    daw-cli plugin list --filter "FabFilter" --category effect --head 10 --format json
    ```
    - **Success Symbol**: `PLUGIN_LIST`
    - **Options**:
      - `--filter "<substring>"`: Case-insensitive search on name or vendor.
      - `--category effect|instrument` (or `fx`, `synth`).
      - `--head <int>` / `--tail <int>`: Limit output row count.
    
    #### Add Plugin to Track Slot
    ```bash
    daw-cli plugin add --track 1 --name "FabFilter Pro-Q 3" --slot 0
    ```
    - **Success Symbol**: `PLUGIN_ADDED`
    - **Options**:
      - `--track <range>`
      - `--name "<exact_name>"` (Must match exact case returned by `plugin list`) or `--id <uint32>`
      - `--slot <0..7>` (Default: 0)
    
    #### Set Plugin Parameter Value
    ```bash
    daw-cli plugin set-param --track 1 --plugin 0 --param 3 --val 0.75
    ```
    - **Success Symbol**: `PLUGIN_PARAM_UPDATED`
    - **Options**:
      - `--track <uint32>`
      - `--plugin <slot_0..7>` (or `--slot`)
      - `--param <param_index>`
      - `--val <float_0.0_to_1.0>` (Normalized range)
    
    #### Copy Single Plugin to Other Tracks
    ```bash
    daw-cli plugin copy --from-track 1 --slot 0 --to-tracks 2..5 --overwrite
    ```
    - **Success Symbol**: `PLUGIN_COPIED`
    - **Options**:
      - `--from-track <uint32>`
      - `--slot <0..7>`
      - `--to-tracks <range>`
      - `--overwrite`: Required if target slots are already occupied.
    
    #### Copy Entire Plugin Insert Chain
    ```bash
    daw-cli plugin copy-chain --from-track 1 --to-tracks 2..5 --overwrite
    ```
    - **Success Symbol**: `PLUGIN_CHAIN_COPIED`
    - **Options**:
      - `--from-track <uint32>`
      - `--to-tracks <range>`
      - `--overwrite`: Required if any target slot in 0..7 is occupied.
    
    ---
    
    ### 4. Session Preparation (prep)
    
    #### Gain-Stage Track Headroom
    Adjusts track fader gains to achieve requested target RMS headroom.
    ```bash
    daw-cli prep gain-stage --track 1..8 --target-rms -18.0
    ```
    - **Success Symbol**: `GAIN_STAGE_COMPLETED`
    - **Options**: `--track <range>`, `--target-rms <float_dB>` (Default: `-18.0`)
    
    ---
    
    ### 5. Clips & Timeline Editing (clip, midi)
    
    #### Add Audio Clip
    ```bash
    daw-cli clip add-audio --track 1 --path "/audio/vocal.wav" --start 1.1.0
    ```
    - **Success Symbol**: `CLIP_ADDED`
    - **Options**: `--track <uint32>`, `--path "<string>"`, `--start <BBT>`
    
    #### Add MIDI Clip
    ```bash
    daw-cli clip add-midi --track 1 --start 1.1.0 --dur 4.0.0
    ```
    - **Success Symbol**: `CLIP_ADDED`
    - **Options**: `--track <uint32>`, `--start <BBT>`, `--dur <BBT>`
    
    #### Add MIDI Note Event
    ```bash
    daw-cli midi add-note --track 1 --clip 1 --pitch C4 --velocity 100 --start 1.1.0 --dur 1.0.0
    ```
    - **Success Symbol**: `MIDI_NOTE_ADDED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--pitch <musical_note, e.g. C4, A5, Db5 or integer 0..127>`, `--velocity <0..127>`, `--start <BBT>`, `--dur <BBT>`
    
    #### List Arrangement Clips
    ```bash
    daw-cli clip list --track 1 [--bar 1-8]
    ```
    - **Success Symbol**: `CLIP_LIST`
    - **Options**: `--track <uint32>`, `--bar <start_bar-end_bar>`
    
    #### Set Clip Gain (dB)
    ```bash
    daw-cli clip set-gain --track 1 --clip 1 --db -3.0
    ```
    - **Success Symbol**: `CLIP_GAIN_UPDATED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--db <float>`
    
    #### Mute / Unmute Clip
    ```bash
    daw-cli clip set-mute --track 1 --clip 1 --on true
    ```
    - **Success Symbol**: `CLIP_MUTE_UPDATED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--on <true|false>`
    
    #### Split Clip
    ```bash
    daw-cli clip split --track 1 --clip 1 --at 2.1.0
    ```
    - **Success Symbol**: `CLIP_SPLIT`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--at <BBT>`
    
    #### Trim Silence
    ```bash
    daw-cli clip trim-silence --track 1 --clip 1 --threshold -48.0 --fade-ms 5.0
    ```
    - **Success Symbol**: `CLIP_SILENCE_TRIMMED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--threshold <float_dB>`, `--fade-ms <float>`
    
    #### Quantize Clip / MIDI
    ```bash
    daw-cli clip quantize --track 1 --clip 1 --grid 1/16 --strength 1.0
    ```
    - **Success Symbol**: `MIDI_CLIPS_QUANTIZED` / `CLIPS_QUANTIZED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--grid <grid_fraction>`, `--strength <float_0..1>`
    
    #### Merge Clips
    ```bash
    daw-cli clip merge --track 1 --start 1.1.0 --end 5.1.0
    ```
    - **Success Symbol**: `CLIPS_MERGED`
    - **Options**: `--track <uint32>`, `--start <BBT>`, `--end <BBT>`, `--clips "<list>"`
    
    #### Move Clip
    ```bash
    daw-cli clip move --track 1 --clip 1 --to-pos 3.1.0 [--to-track 2]
    ```
    - **Success Symbol**: `CLIP_MOVED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--to-pos <BBT>`, `--to-track <uint32>`
    
    #### Nudge Clip Position
    ```bash
    daw-cli clip nudge --track 1 --clip 1 --by +1/16
    ```
    - **Success Symbol**: `CLIP_NUDGED`
    - **Options**: `--track <uint32>`, `--clip <uint32>`, `--by <+|-grid_fraction>`
    
    ---
    
    ### 6. Signal Routing & Topology (route)
    
    #### Route Tracks to Bus / Folder
    Routes source track outputs to a destination bus or folder track, updating both audio routing and parent folder hierarchy.
    ```bash
    daw-cli route folder --track 1..4 --to 10
    ```
    - **Success Symbol**: `ROUTE_FOLDER_UPDATED`
    - **Options**: `--track <range>`, `--to <bus_track_id>`
    
    #### Add Aux Send
    Configures a pre-fader or post-fader send from source tracks to a target Aux track with gain level in dB.
    ```bash
    daw-cli route send --from 1..4 --to 14 --db -12.0 --tap post
    ```
    - **Success Symbol**: `ROUTE_SEND_ADDED`
    - **Options**: `--from <range>`, `--to <aux_track_id>`, `--db <float_dB>` (Default: `-12.0`), `--tap pre|post` (Default: `post`)
    
    #### Set Up Sidechain Connection
    Links a trigger source track as a sidechain input into a target track's plugin or instrument slot.
    ```bash
    daw-cli route sidechain --source 1 --to-track 9 --slot 0 --db 0.0
    ```
    - **Success Symbol**: `ROUTE_SIDECHAIN_LINKED`
    - **Options**: `--source <track_id>`, `--to-track <track_id>`, `--slot <0..7>` (Default: `0`), `--db <float_dB>` (Default: `0.0`)
    
    #### List Routing Topology
    Lists signal routing connections, main outputs, sends, and sidechains across all tracks.
    ```bash
    daw-cli route list [--format tsv|kv|json|pretty]
    ```
    - **Success Symbol**: `ROUTE_LIST`
    
    ---
    
    ### 7. Non-Visual DSP Analysis & Audio Intelligence (analyze)
    
    Domain 6 provides a non-visual DSP analysis and audio intelligence suite across 9 specialized subcommands, supporting both **Short Frame** (real-time telemetry) and **Full Track** (offline decoded asset) processing.
    
    #### Frequency Masking & Collision Detection
    Calculates psychoacoustic masking overlap and energy density collisions across 24 critical Bark bands between two tracks using Schroeder spreading functions.
    ```bash
    daw-cli analyze masking --track 1 --vs 2 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_MASKING`
    - **Options**: `--track <uint32>`, `--vs <uint32>`
    - **Output Fields**: `PRIMARY_TRACK`, `VS_TRACK`, `OVERALL_MASKING_INDEX` ($C_{A,B} \in [0.0, 1.0]$), `COLLISION_RISK` (`LOW_MASKING`, `MODERATE_MASKING`, `HIGH_MASKING`), `MASKED_BAND_COUNT`, `BAND_1_RANGE_HZ`, `BAND_1_MASK_AMOUNT_DB`, `BAND_1_RECOMMENDED_ACTION` (`SIDECHAIN_DUCK_PRIMARY_LOWS`, `CUT_VS_TRACK_EQ_<freq>HZ`), ...
    
    #### Narrow-Q Resonance Peak Detection
    Scans track audio spectrum with a 31-bin moving median spectral envelope filter to isolate harsh narrow-Q resonances, pitch note names, and Q-factor sharpness ($Q \ge 8.0$).
    ```bash
    daw-cli analyze resonance --track 1 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_RESONANCE`
    - **Options**: `--track <uint32>`
    - **Output Fields**: `TRACK_ID`, `TOTAL_RESONANCES_FOUND`, `RESONANCE_1_FREQ_HZ`, `RESONANCE_1_NOTE` (e.g. `E4`, `A5`), `RESONANCE_1_PROMINENCE_DB`, `RESONANCE_1_Q_FACTOR`, `RESONANCE_1_SEVERITY` (`HIGH_SEVERITY_SURGICAL_CUT`, `MODERATE`), `RESONANCE_1_REC_NOTCH_DB`
    
    #### Multi-Track Pearson Phase Correlation Matrix
    Computes an $N \times N$ pairwise Pearson correlation matrix ($r_{i,j}$) across a list or range of tracks to flag phase cancellation risks and identify destructive anti-phase pairs.
    ```bash
    daw-cli analyze phase-matrix --track 1..4 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_PHASE_MATRIX`
    - **Options**: `--track <range|list>` (e.g. `1..4`, `1,2,3,4`)
    - **Output Fields**: `TRACKS_ANALYZED`, `GLOBAL_GROUP_HEALTH` (`HEALTHY_MONO_COMPATIBLE`, `WARNING_SEVERE_CANCELLATION`), `WORST_PAIR_1`, `WORST_CORRELATION_1`, `REC_ACTION_1` (`FLIP_POLARITY_TRACK_<id>`, `NUDGE_DELAY_TRACK_<id>`), `CORRELATION_MATRIX_FLAT`
    
    #### Cross-Correlation Phase Alignment
    Calculates cross-correlation lag across $[-128, +128]$ sample offsets to recommend sample-accurate and millisecond time shifts ($\Delta t_{\text{ms}} = \frac{\text{offset}}{f_s} \times 1000$).
    ```bash
    daw-cli analyze phase-align --track 1 --vs 2 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_PHASE_ALIGN`
    - **Options**: `--track <uint32>`, `--vs <uint32>`
    - **Output Fields**: `PRIMARY_TRACK`, `VS_TRACK`, `RECOMMENDED_SAMPLE_OFFSET`, `RECOMMENDED_TIME_OFFSET_MS`, `CURRENT_CORRELATION`, `IMPROVED_CORRELATION`, `RECOMMENDED_ACTION` (e.g. `NUDGE_REGION_TRACK_2_BY_-48_SAMPLES`)
    
    #### Window Offline Telemetry
    Performs offline telemetry analysis over a specified timeline range for momentary/short-term EBU R128 BS.1770 LUFS, true-peak dBTP, crest factor, and safety gain trim.
    ```bash
    daw-cli analyze window --track 1 --start 1.1.0 --dur 4.0.0 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_WINDOW_STREAM`
    - **Options**: `--track <uint32>`, `--start <BBT>`, `--dur <BBT>`
    - **Output Fields**: `TRACK_ID`, `START_POS`, `DUR_POS`, `MOMENTARY_LUFS`, `SHORT_TERM_LUFS`, `SAMPLE_PEAK_DBFS`, `TRUE_PEAK_DBTP`, `IS_CLIPPING`, `CLIPPING_EVENTS_COUNT`, `CREST_FACTOR_DB`, `SPECTRAL_CENTROID_HZ`, `STEREO_CORRELATION`, `SAFETY_STATUS` (`SAFE_NORMAL`, `VIOLATION_DANGER_REDUCE_GAIN`), `REC_GAIN_TRIM_DB`
    
    #### 7-Band Spectral Energy Balance
    Evaluates acoustic energy distribution across 7 standardized bands (Sub: 20-60Hz, Bass: 60-250Hz, Low-Mid: 250-500Hz, Mid: 500-2kHz, High-Mid: 2-4kHz, Highs: 4-8kHz, Air: 8-20kHz) alongside spectral centroid, 85% energy rolloff frequency, and spectral tilt (dB/octave).
    ```bash
    daw-cli analyze spectrum --track 1 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_SPECTRUM`
    - **Options**: `--track <uint32>`
    - **Output Fields**: `TRACK_ID`, `SPECTRAL_CENTROID_HZ`, `SPECTRAL_TILT_DB_OCT`, `SPECTRAL_ROLLOFF_HZ`, `SUB_BAND_DBFS`, `BASS_BAND_DBFS`, `LOW_MID_BAND_DBFS`, `MID_BAND_DBFS`, `HIGH_MID_BAND_DBFS`, `HIGHS_BAND_DBFS`, `AIR_BAND_DBFS`
    
    #### EBU R128 Loudness Audit (Full Track / Real-Time)
    Performs ITU-R BS.1770-4 / EBU R128 integrated loudness, loudness range (LRA), short-term/momentary peak LUFS, sample peak, and crest factor.
    ```bash
    daw-cli analyze loudness --track 1 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_LOUDNESS`
    - **Options**: `--track <uint32>`
    - **Output Fields**: `TRACK_ID`, `INTEGRATED_LUFS`, `SHORT_TERM_MAX_LUFS`, `MOMENTARY_MAX_LUFS`, `LRA_LU`, `CREST_FACTOR_DB`, `SAMPLE_PEAK_DBFS`, `TRUE_PEAK_DBTP`
    
    #### True-Peak Inter-Sample Clipping Audit
    Performs 4x oversampled true-peak analysis to detect inter-sample clipping events and safety margin status ($0.0\text{ dBTP}$ threshold).
    ```bash
    daw-cli analyze true-peak --track 1 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_TRUE_PEAK`
    - **Options**: `--track <uint32>`
    - **Output Fields**: `TRACK_ID`, `MAX_TRUE_PEAK_DBTP`, `TOTAL_CLIPPING_EVENTS`, `SAFETY_STATUS` (`SAFE_NORMAL`, `VIOLATION_DANGER`)
    
    #### Mid/Side Stereo Width Audit
    Measures Mid RMS ($0.5(L+R)$), Side RMS ($0.5(L-R)$), Mid-to-Side ratio in dB, stereo width percentage, and mono fold-down cancellation loss in dB.
    ```bash
    daw-cli analyze stereo-width --track 1 [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `ANALYSIS_STEREO_WIDTH`
    - **Options**: `--track <uint32>`
    - **Output Fields**: `TRACK_ID`, `MID_RMS_DBFS`, `SIDE_RMS_DBFS`, `MS_RATIO_DB`, `STEREO_WIDTH_PCT`, `MONO_FOLD_LOSS_DB`
    
    ---
    
    ## 8. Export & Asynchronous Render Jobs (`export`, `job`)
    
    The `export` and `job` command suites allow agents to trigger offline full-mix bounces, export multi-track stems, and asynchronously query or cancel active rendering jobs.
    
    ### 8.1 Master Mixdown Export (`export master`)
    
    Enqueues an offline bounce of the full master arrangement or loop selection.
    
    ```bash
    daw-cli export master --output <path> [options]
    ```
    
    - **Options**:
      - `--output, -o <path>`: Destination audio file path (e.g. `/tmp/mixdown.wav`).
      - `--format <wav|flac|mp3|aiff|ogg>`: Audio codec (default: `wav`).
      - `--bit-depth <16|24|32>`: Sample precision (default: `24`).
      - `--sample-rate <uint>`: Target sample rate in Hz (default: project sample rate).
      - `--dither <on|off>`: Psychoacoustic TPDF dither injection (default: `on`).
      - `--split-planar <on|off>`: Export split Left/Right planar files (default: `off`).
      - `--normalize <on|off>`: Enable peak normalization (default: `off`).
      - `--norm-db <float>`: Target peak in dBFS (e.g. `-0.1`).
      - `--range <full|loop>`: Render arrangement timeline or active loop region (default: `loop` if looping is enabled, else `full`).
      - `--tail-ms <uint>`: Reverb/decay tail in milliseconds for full arrangement bounces (default: `1000`).
    - **Success Symbol**: `EXPORT_JOB_STARTED`
    - **Output Fields**: `job_id`, `type`, `format`, `sample_rate`, `bit_depth`, `destination`
    
    ### 8.2 Stem Export (`export stems`)
    
    Enqueues multi-track stem exports across selected session tracks.
    
    ```bash
    daw-cli export stems --output <directory> [options]
    ```
    
    - **Options**:
      - `--output, -o <directory>`: Target directory where stem files will be saved (e.g. `/tmp/stems/`).
      - `--track <range|all>`: Track index range (`1..8`, `1,2,5`, or `all`).
      - `--naming-pattern <pattern>`: Filename pattern token (default: `"{track_index:02d}_{track_name}"`, option: `"{project}_{track_name}"`).
      - `--format <wav|flac|mp3|aiff|ogg>`: Codec (default: `wav`).
      - `--bit-depth <16|24|32>`: Sample bit depth (default: `24`).
      - `--sample-rate <uint>`: Target sample rate (default: project sample rate).
      - `--print-sends`: Print auxiliary send returns into track stems (wet bounce).
      - `--bypass-sidechain`: Disable mixdown sidechain ducking during export (default: active).
      - `--range <full|loop>`: Bounds selection.
      - `--tail-ms <uint>`: Decay tail duration in milliseconds.
      - `--normalize <on|off>`: Stem peak normalization.
      - `--norm-db <float>`: Target peak in dBFS.
    - **Success Symbol**: `STEM_EXPORT_STARTED`
    - **Output Fields**: `job_id`, `type`, `total_tracks`, `format`, `sample_rate`, `destination`
    
    ### 8.3 Job Queue Management (`job`)
    
    #### Listing Jobs
    Lists all active, queued, and completed render jobs.
    ```bash
    daw-cli job list [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `JOB_LIST`
    - **Output Columns**: `JOB_ID`, `NAME`, `TYPE`, `STATUS`, `PROGRESS`, `OUTPUT`
    
    #### Querying Job Status
    Queries real-time progress and status details for a specific job.
    ```bash
    daw-cli job status --id <job_id> [--format json|tsv|kv|pretty]
    ```
    - **Success Symbol**: `JOB_STATUS`
    - **Output Fields**: `job_id`, `name`, `type`, `status`, `progress`, `status_message`, `destination`, `current_track_index`, `total_tracks`
    
    #### Cancelling a Job
    Aborts an in-progress or queued background render job.
    ```bash
    daw-cli job cancel --id <job_id>
    ```
    - **Success Symbol**: `JOB_CANCELLED`
    - **Output Fields**: `job_id`
    
    ---
    
    ## Common Workflows
    
    ### Workflow A: Setting Up a 4-Track Drum Session
    ```bash
    # 1. Verify DAW application connection
    daw-cli status
    
    # 2. Batch-create drum tracks
    daw-cli track create-batch --names "Kick,Snare,HiHat,Tom" --type audio
    
    # 3. Clean up track names and apply instrument colors
    daw-cli track sanitize-names
    daw-cli track auto-color
    
    # 4. Gain stage all drum tracks to -18 dB RMS headroom
    daw-cli prep gain-stage --track 1..4 --target-rms -18.0
    ```
    
    ### Workflow B: Applying and Distributing an EQ Plugin Chain
    ```bash
    # 1. Search for available EQ plugins
    daw-cli plugin list --filter "EQ" --category effect --format json
    
    # 2. Add EQ plugin to slot 0 of Vocal Lead (Track 1)
    daw-cli plugin add --track 1 --name "FabFilter Pro-Q 3" --slot 0
    
    # 3. Copy EQ plugin from Track 1 slot 0 to Backing Vocals (Tracks 2..5)
    daw-cli plugin copy --from-track 1 --slot 0 --to-tracks 2..5 --overwrite
    ```
    
    ### Workflow C: Submix Bus & Sidechain Setup
    ```bash
    # 1. Route drum tracks 1..4 into Drums Bus (Track 10)
    daw-cli route folder --track 1..4 --to 10
    
    # 2. Add post-fader send from Snare (Track 2) to Reverb Aux (Track 14) at -12 dB
    daw-cli route send --from 2 --to 14 --db -12.0 --tap post
    
    # 3. Link Kick (Track 1) as sidechain trigger to Synth Bass (Track 9) slot 0
    daw-cli route sidechain --source 1 --to-track 9 --slot 0 --db 0.0
    
    # 4. Inspect session routing topology
    daw-cli route list --format tsv
    ```
    
    ### Workflow D: Acoustic Guitar & Vocal Masking Audit and Resonant Notch Fix
    ```bash
    # 1. Analyze frequency masking between Vocal (Track 1) and Acoustic Guitar (Track 2)
    daw-cli analyze masking --track 1 --vs 2
    
    # 2. Detect harsh resonant peaks and Q-factors on Acoustic Guitar
    daw-cli analyze resonance --track 2
    
    # 3. Evaluate multi-mic phase alignment between Top Snare (Track 3) and Bottom Snare (Track 4)
    daw-cli analyze phase-align --track 3 --vs 4
    
    # 4. Perform offline windowed LUFS & True-Peak telemetry on Master Output (Track 10)
    daw-cli analyze window --track 10 --start 1.1.0 --dur 4.0.0
    ```
    
    ### Workflow E: Bouncing Master Mixdown and Exporting Stems
    ```bash
    # 1. Export 24-bit 48kHz master mixdown with -0.1 dBFS normalization
    daw-cli export master --output "/tmp/mixdown.wav" --format wav --bit-depth 24 --normalize on --norm-db -0.1
    
    # 2. Export drum stems (tracks 1 to 4) to directory
    daw-cli export stems --output "/tmp/stems/" --track 1..4 --format wav --bit-depth 24
    
    # 3. Check active render jobs
    daw-cli job list
    
    # 4. Poll specific job status until completed
    daw-cli job status --id 1
    ```
    
    ---
    
    ## Common Mistakes
    
    1. **Plugin Name Case Sensitivity**:
       `daw-cli plugin add --name` requires an **exact case-sensitive match**. `plugin add --name "fabfilter pro-q 3"` will fail with `72 ENTITY_NOT_FOUND`. Always run `plugin list --filter "FabFilter"` first to copy the exact name string.
    
    2. **Forgetting `--overwrite` on Occupied Plugin Slots**:
       Copying plugins (`plugin copy` or `plugin copy-chain`) to tracks with existing plugins in target slots without `--overwrite` will fail with error `74 RESOURCE_BUSY_USER_TOUCH`.
    
    3. **Not Checking `status` Before Issuing Commands**:
       Attempting to execute commands when Stratawright is closed returns error `71 DAW_NOT_RUNNING`. Always run `daw-cli status` first to confirm connectivity.
    
    4. **Missing Comparison Target for Pairwise Analysis**:
       Commands like `daw-cli analyze masking` and `daw-cli analyze phase-align` require `--vs <target_track_id>`. Omitting `--vs` returns error `70 INVALID_ARGS`.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.