ferraus stretch

Change duration, keep pitch

Synopsis

ferraus stretch <input> [options] [-o <output>]

Time-stretches without changing pitch. auto mode detects transients, keeps every attack intact and exactly on time (onset × factor), and renders tonal stretches with a phase vocoder and percussive ones with WSOLA. --factor 1.0 returns the input bit for bit. Give a factor, a target duration (--to), or a tempo change (--bpm 120 --to-bpm 128; without --bpm the source tempo is estimated).

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "stretch:key=value".

Examples

25% longer, same pitch

ferraus stretch loop.wav --factor 1.25 -o slower.wav

Fit the song into 3:30

ferraus stretch song.wav --to 3:30 -o radio.wav

Re-tempo a drum loop from 120 to 128 BPM

ferraus stretch beat.wav --bpm 120 --to-bpm 128 --mode percussive -o faster.wav

Options

Flag	Type	Default	Meaning
`--factor`	number	`1.0`	Duration multiplier: 2.0 is twice as long, 0.5 half as long Range: 0.05..20.
`--to`	time	—	Target duration instead of a factor, e.g. 3:30 or 95s
`--bpm`	number	—	Source tempo for --to-bpm (also the global --bpm); estimated when omitted
`--to-bpm`	number	—	Target tempo; the factor is bpm / to-bpm
`--mode`	auto \| tonal \| percussive \| speech	`auto`	auto: per-segment vocoder/WSOLA hybrid; tonal: vocoder only; percussive: WSOLA with transient preservation; speech: hybrid with short windows
`--quality`	high \| fast	`high`	high: hybrid as above; fast: WSOLA only (tonal mode: short vocoder)

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 --overwrite or a new -o path when re-running.
Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.

For models

MCP tool: ferraus_stretch
Schema: ferraus schema stretch
Pipeline: { op: stretch, args: { ... } } (flag names with _ instead of -)
fx stage: yes

{"command": "stretch", "defaults": {"factor": "1.0", "mode": "auto", "quality": "high"}}