Name: DigWash
Author: DigWash

01 · Before the first track

Install and identify DigWash

TODO — distribution gate. The CLI ships as a standalone per-platform binary download (no Python, no package manager), Apple Silicon first, then Intel Mac, Windows, and Linux. Before release, replace this notice with the verified download, unpack/unquarantine, and removal steps for each shipped platform, then copy-paste-test them. All platforms ship today; the download links travel in the beta access email — join the beta to get yours.

DigWash ships as proprietary beta software under the DigWash Beta End User License Agreement: free for personal, noncommercial DJ use during the beta, with the full terms bundled as LICENSE.md in every download.

Once you have received an approved beta artifact, these read-only checks identify the executable:

digwash --version
command -v digwash        # macOS / Linux shell
where digwash             # Windows Command Prompt

Expected version for this manual: DigWash 0.1.0. If your version differs, use that release’s manual and help output.

02 · Safe quickstart

Your first ten minutes

Use a disposable copy or a track you know well. Quote paths containing spaces. The examples use placeholders—replace them with your own paths.

1. Read the track

digwash check "/path/to/dig/track.flac" --no-color

check reads audio and metadata for analysis. It writes no music, playlist, or database.

2. Preview a compatibility copy

digwash convert "/path/to/dig/track.flac" --dry-run --no-color

The preview names the source, planned action, and destination. By default a converted file lands beside its source. An existing destination is an error unless you explicitly add --overwrite.

3. Commit only after reading the plan

digwash convert "/path/to/dig/track.flac" --out-dir "/path/to/output" --commit

-y, --commit, and --yes are aliases. The source remains untouched unless you explicitly request --trash-sources. Conversion makes a playback-compatible copy; it cannot restore quality absent from the source.

TODO — packaged smoke transcript. Run these three commands against the final packaged beta and a disposable audio fixture; insert the exact preview destination and committed filename after verifying them. The source currently proves the rules, but release evidence is still missing.

03 · Read the plan

Core concepts

Call: The analysis verdict and its reasons. A clean call does not guarantee every booth can load the file.
Compatibility: A codec, sample-rate, bit-depth, and bitrate comparison against DigWash’s shipped deck-family matrix. “Unknown” means DigWash lacks enough supported evidence; it is not a promise that a file plays.
Warning: Something worth a listening check. It is not automatically a repair instruction.
Planned action: What a writing command would copy, convert, rename, skip, or add to a playlist. Preview before commit.

--dry-run forces preview even in a workflow that might otherwise ask for confirmation. Writing commands never silently overwrite; destructive-looking options are explicit.

04 · Work by task

Recipes

One track

digwash check "/path/to/track.flac"
digwash convert "/path/to/track.flac" --out-dir "/path/to/clean" --dry-run
digwash convert "/path/to/track.flac" --out-dir "/path/to/clean" -y

A digging folder

digwash wash "/path/to/session" --dry-run
digwash wash "/path/to/session" -y

The default target is a sibling <folder>-clean directory containing the curated copies and a co-located playlist. Use --out DIR to choose another target.

An M3U/M3U8 playlist

digwash wash "/path/to/session.m3u8" --dry-run
digwash wash "/path/to/session.m3u8" -y

Playlist input resolves the tracks as the wash set. On commit, DigWash writes a new co-located playlist named <name>-dw.<ext> beside the original — the same convention as convert — preserving the original’s extension and leaving the original playlist untouched (unless you pass --in-place).

A flat master database

digwash crate "/path/to/session" --database "/path/to/master" --dry-run
digwash crate "/path/to/session" --database "/path/to/master" -y

crate defaults to a flat database and writes an M3U playlist. Use it only when you want a persistent master collection; wash is the simpler post-dig cleanup path.

05 · Booth choices

Presets, in DJ language

Run digwash presets for the coded rules. Least to most conversion:

Keep everything (keep-all) — no compatibility conversion.
Hi-res decks (true-lossless-booth) — the newest hi-res players (CDJ-3000, CDJ-2000NXS2); keeps FLAC and ALAC, converts OGG, caps above 96 kHz to 96 kHz. Preserves the most quality.
FLAC decks (modern-booth) — modern FLAC decks that don't read ALAC (e.g. XDJ-RX3, XDJ-XZ); keeps FLAC, converts ALAC and OGG, caps above 48 kHz to 48 kHz.
Any USB booth (any-booth, default) — converts FLAC, OGG and confirmed ALAC-in-M4A to AIFF and re-encodes MP3/AAC above 320 kbps down to 320, caps above 48 kHz to 48 kHz, so tracks load on any USB deck we've checked, old or new. 24-bit is kept.
Burn an audio CD (audio-cd) — Red Book audio (16-bit / 44.1 kHz PCM) or MP3 for CD-era disc decks. Not available yet — lands in V1.

More conversion means broader playback targets, not better sound. Inspect your actual booth with digwash machines; if the model or file facts are unknown, listening and a deck test remain the honest fallback.

06 · Installed surface

Command reference

This inventory comes from digwash --help for version 0.1.0. Run digwash COMMAND --help for the authoritative flag list installed on your machine.

Command	Job
`check`	Analyze files, folders, or a playlist. Read-only.
`convert`	Preview or write CDJ-safe copies of files, folders, or a playlist.
`wash`	Build a curated set and co-located playlist from a folder or playlist.
`crate`	Import a session into a master database and write a playlist.
`calibrate`	Adapt warning thresholds from tracks you trust (and optionally reject).
`presets`	Print the exact conversion rules for every preset.
`explain`	Explain a quality term, for example peak or fake lossless.
`machines`	Print the CDJ/XDJ playback-compatibility matrix; accepts --json.
`capabilities`	Print version, schema, commands, presets, and runtime availability as JSON.

`check PATH…`

Accepts files, folders, and M3U/M3U8. Key flags: --json (JSON Lines), --no-color, --no-spectral, --jobs N.

`convert PATH…`

Key flags: --preset, --out-dir, --overwrite, --trash-sources, playlist-only --in-place, commit/dry-run, JSON, plain output, verbose.

`wash FOLDER|PLAYLIST`

Key flags: mutually exclusive --out DIR/--in-place, preset, conservative name/tag cleanup, commit/dry-run, JSON, analysis workers. In-place mode visibly prefixes superseded originals with _superseded_ ; it does not delete them.

`crate [FOLDER]`

Supports TOML config or folder/database paths; flat, tags, or mirror structure; optional name/tag cleanup; detail/forensic analysis; recoverable source trashing; commit/dry-run; JSON and worker controls.

`calibrate [GOOD PATH…]`

Use --bad PATH… and --reason to sharpen warnings, --show to inspect the baseline, and --reset to delete it. Calibration changes stored warning behavior; preview it conceptually as a trust operation, not audio repair.

`presets`

Prints exact coded preset rules. No writing flags.

`explain TERM…`

Explains one or more DigWash quality terms.

`machines [--json]`

Reports what the shipped compatibility matrix says plays on what.

`capabilities`

Always emits a JSON envelope describing version, schema, commands, presets, stages, and runtime.

07 · Advanced

JSON and automation

check --json emits JSON Lines; the other JSON-capable workflows use machine-readable envelopes or streams. Do not parse styled human output. Check schema_version, ok, error, and warnings, and discover the installed contract with:

digwash capabilities
digwash machines --json

Keep stderr as well as stdout when diagnosing conversion. The process exit code is a supported contract you can branch on: 0 success, 1 a runtime or analysis error, 2 a usage error (missing or invalid command or arguments), and 130 an interrupt (Ctrl-C). Pair these with the JSON ok/error fields when you need machine-readable detail.

08 · High-trust operations

Safety and recovery

Preview is the default for convert, wash, and crate; check is read-only.
Existing destinations fail unless convert --overwrite is explicit.
--trash-sources moves sources to the system Trash only after successful work; it is off by default.
wash --in-place keeps superseded originals under a visible prefix for manual cleanup.
If interrupted, do not rerun with overwrite blindly. Inspect the destination, keep completed files, then preview again.

09 · When the wash stops

Troubleshooting

`digwash: command not found`

Confirm you used the approved beta installer, restart the terminal, and use the path checks above. TODO: add channel-specific PATH repair after distribution is approved.

Unreadable or unsupported file

Run digwash check FILE --no-color. Confirm the path, extension, and read permission. Keep the original; an unsupported codec is not permission to rename or transcode blindly.

Permission denied

Choose an output directory you own with --out-dir or --out. Avoid elevated/admin execution around a music library.

Destination already exists

Compare the files or choose a new destination. Use convert --overwrite only when replacement is intentional; other workflows do not promise silent replacement.

Conversion was interrupted

Keep the source. Inspect partial destinations, rerun a dry preview, and only then decide whether an explicitly replaceable destination should be removed or overwritten.

10 · Make it reproducible

Report a problem without sharing music

Send the DigWash version, operating system, command with paths anonymized, --no-color output, expected result, actual result, and whether it was preview or commit. Add codec/container/sample-rate/bit-depth facts if safe. Never upload the track unless you own it and explicitly choose to.

Send beta feedback → Read the evidence behind the calls →

Wash a dig without gambling the originals.