ferraus phase-align
Align the timing of channels (azimuth and mic-placement correction)
Synopsis
ferraus phase-align <input> [options] [-o <output>]
What it does
In 'auto' mode, cross-correlates the channels window by window, takes a confidence-weighted median of the per-window delays (to sub-sample precision), and advances the late channel so the channels line up. In 'shift' mode, applies the delays you give per channel (positive delays, negative advances). The length is unchanged. The metrics report the shift and the inter-channel correlation before and after.
This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "phase-align:key=value".
Examples
Fix tape azimuth error automatically
ferraus phase-align tape.wav -o aligned.wav
Delay the right channel by 12 samples
ferraus phase-align room.wav --mode shift --shift L=0smp,R=12smp -o aligned.wav
Longer analysis windows and a 2 ms search limit for a close stereo mic pair
ferraus phase-align xy_pair.wav --window 500ms --max-shift 2ms -o aligned.wav
Delay the left channel by a quarter of a millisecond
ferraus phase-align overheads.wav --mode shift --shift L=0.25ms,R=0smp -o aligned.wav
Options
| Flag | Type | Default | Meaning |
|---|---|---|---|
--mode | auto | shift | auto | Detect the delay automatically, or apply --shift |
--shift | text | L=0smp,R=0smp | Per-channel delays for --mode shift (L=0smp,R=12smp; times like 0.25ms also work) |
--window | time | 200ms | Analysis window length for auto mode (time) |
--max-shift | time | 5ms | Largest delay searched in auto mode (time) |
--mix | percent | 100% | Dry/wet balance: 0% returns the input unchanged, 100% is fully processed |
Global options
Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Processing failed |
| 2 | Usage or parameter error |
| 3 | Input missing or unreadable |
| 4 | Unsupported format or codec |
| 8 | Cancelled |
| 70 | Internal error (bug) |
Common mistakes
- Forgetting that outputs are never overwritten: pass
--overwriteor a new-opath when re-running. - Beat-based times (
4b,1/4) need a tempo: pass--bpmor write4b@120.
For models
- MCP tool:
ferraus_phase_align - Schema:
ferraus schema phase-align - Pipeline:
{ op: phase-align, args: { ... } }(flag names with_instead of-) - fx stage: yes
{"command": "phase-align", "defaults": {"mode": "auto", "shift": "L=0smp,R=0smp", "window": "200ms", "max_shift": "5ms", "mix": "100%"}}