$ recs --help
usage: recs [-h] [OPTIONS] [[PATH [PATH ...]]]

  🎙 recs: The Universal Recorder 🎙
=============================================

Why should there be a record button at all?

I wanted to digitize a huge number of cassettes and LPs, so I wanted a program that ran in the background and recorded everything except quiet.

Nothing like that existed so I wrote it.  Free, open-source, configurable.

Full documentation here: https://github.com/rec/recs

With no subcommand, recs starts recording. sessions ROOT lists recordings; session COMMAND manages one recording; record check PATH validates a recording document and its media.

control pause/resume affect capture; control stop/continue affect playback. project manages saved recording projects; mute manages a machine-wide microphone exclusion; --profiles loads per-device JSON defaults.

readiness inspects a project or configuration without recording; preflight checks a running daemon.

 positional arguments
 -------------------------------------------------------------------------------------------
  [[PATH [PATH ...]]]
        One or more files to split for silence (default: )

 options
 -------------------------------------------------------------------------------------------
  -h, --help
        show this help message and exit

 directory options
 -------------------------------------------------------------------------------------------
  -o STR, --output-directory STR
        Path or output_directory pattern for recorded file locations (default: '')
  --short-file-names, --no-short-file-names
        Omit the device from generated names when there is only one (default: True)

 general options
 -------------------------------------------------------------------------------------------
  --calibrate, --no-calibrate
        Detect and print noise levels, do not record (default: False)
  --default-record-directory STR
        Directory name to use for automatic daemon recordings (default: recs)
  -n, --dry-run, --no-dry-run
        Display levels only, do not record (default: False)
  -v, --verbose, --no-verbose
        Print more stuff (default: False)
  --info, --no-info
        Display device info as JSON (default: False)
  --list-types, --no-list-types
        List all subtypes for each format as JSON (default: False)
  --silence-preview, --no-silence-preview
        Show live silence measurements and suggested recording thresholds (default: False)
  --save-settings {None,True,False}
        Save mutable API settings for the next recording run (default: None)

 device options
 -------------------------------------------------------------------------------------------
  -a STR, --alias STR
        Set aliases for devices or channels (repeatable)
  --devices PATH
        A path to a JSON file with device definitions (default: .)
  --profiles PATH
        Per-device JSON defaults, not a recording project (default: .)

 selection options
 -------------------------------------------------------------------------------------------
  -e STR, --exclude STR
        Exclude devices or channels (repeatable)
  -i STR, --include STR
        Only include these devices or channels (repeatable)

 audio options
 -------------------------------------------------------------------------------------------
  -f AUDIO FORMAT, --format AUDIO FORMAT
        Audio file formats (repeatable, appends to: flac)
  -m STR, --metadata STR
        Metadata fields to add to output files (repeatable)
  -d {None}|{NUMERIC TYPE}, --sdtype {None}|{NUMERIC TYPE}
        Integer or float number type for recording (default: float32)
  -u {None}|{AUDIO SUBTYPE}, --subtype {None}|{AUDIO SUBTYPE}
        Audio file subtype (default: None)

 midi options
 -------------------------------------------------------------------------------------------
  --midi, --no-midi, --record-midi, --no-record-midi
        Record MIDI inputs (default: True)
  --midi-include STR
        Only record these MIDI input name prefixes (repeatable)
  --midi-exclude STR
        Exclude these MIDI input name prefixes (repeatable)
  --midi-timing {mido,system}
        MIDI timing: system callback clock, or mido source deltas (default: system)

 osc options
 -------------------------------------------------------------------------------------------
  --osc-nodes PATH
        TOML file describing OSC nodes to record (default: .)

 console options
 -------------------------------------------------------------------------------------------
  -r, --clear-terminal, --no-clear-terminal
        Clear display on shutdown (default: True)
  --gui, --no-gui
        Display live updates in a PySide6 window (default: False)
  --open-output-folder, --no-open-output-folder
        Open the output folder when recording finishes (default: False)
  --remote, --no-remote
        Connect to an already-running recs daemon instead of recording (default: False)
  -s, --silent, --no-silent
        Do not display live updates (default: False)
  --sleep-time-device TIME
        How long to sleep between checking device (default: 0.1)
  --ui-refresh-rate HZ
        How many UI refreshes per second (default: 10.0)
  --waveform-bucket-milliseconds MILLISECONDS
        Milliseconds represented by each live waveform bucket (default: 20)
  --waveform-batch-milliseconds MILLISECONDS
        Milliseconds represented by each live waveform batch (default: 100)

 keys options
 -------------------------------------------------------------------------------------------
  --key-label STR
        Add a record label for a key, for example g=guitar too soft (repeatable)
  --record-keys {None}|{KEY RECORDING MODE}
        Record keys in the session record: none, press, or all (default: None)
  --record-key-all-apps {None,True,False}
        Record key events from all applications; must be explicitly enabled (default: None)

 recording options
 -------------------------------------------------------------------------------------------
  --audio-buffer-seconds TIME
        Seconds of audio to buffer before dropping delayed callbacks (default: 10.0)
  --memory-reserve-megabytes MB
        Free system memory to reserve while buffering audio (default: 200)
  --memory-check-period TIME
        How often to check available system memory (default: 2.0)
  -B, --band-mode, --no-band-mode
        Band mode: any track starting starts them all (default: False)
  --channel-noise-floors [STR [STR {None}|FLOAT [STR {None}|FLOAT ...]] [...]]
        Per-device mono or stereo track noise floor overrides (default: )
  --infinite-length, --no-infinite-length
        Ignore file size limit: 4G on .wav (default: False)
  --longest-file-time TIME
        Longest amount of time per file: 0 means infinite (default: 0.0)
  --minimum-free-space BYTES
        Absolute disk-space reserve used with the emergency threshold (default: 0)
  --disk-alert-thresholds STR
        Free-space alerts, such as 30m or 500MB (repeatable, appends to: 1800s 600s 120s)
  --disk-removable-emergency STR
        Emergency reserve on removable disks (repeatable, appends to: 200000000 30s)
  --disk-system-emergency STR
        Emergency reserve on the system disk (repeatable, appends to: 2000000000 120s)
  --disk-removable-pause STR
        Pause reserve on removable disks (repeatable, appends to: 200000000 30s)
  --disk-system-pause STR
        Pause reserve on the system disk (repeatable, appends to: 2000000000 120s)
  --disk-poll-seconds TIME
        How often to check recording disk space (default: 1.0)
  --card-replace-poll-seconds TIME
        How often to poll for a replacement recording card (default: 1.0)
  --card-replace-timeout-seconds TIME
        How long to wait for a replacement recording card (default: 300.0)
  --flush-time TIME
        How often to sync open audio files (default: 1.0)
  --flush-overlap-time TIME
        Extra audio retained for recording-card failover (default: 1.0)
  --disk-auto-switch, --no-disk-auto-switch
        Switch to a better removable disk after a disk-space alert (default: True)
  --moving-average-time TIME
        How long to average the volume display over (default: 1.0)
  -z FLOAT, --noise-floor FLOAT
        The noise floor in decibels (default: 70.0)
  --preview-headroom FLOAT
        Headroom in decibels to add to silence preview measurements (default: 6.0)
  -R, --record-everything, --no-record-everything
        Start immediately, record everything until end (default: False)
  --shortest-file-time TIME
        Files shorter than this duration get deleted (default: 1.0)
  -c TIME, --quiet-after-end TIME
        How much quiet after the end (default: 10.0)
  -b TIME, --quiet-before-start TIME
        How much quiet before a recording (default: 10.0)
  --stop-after-quiet TIME
        How much quiet before stopping a recording (default: 20.0)
  -t TIME, --total-run-time TIME
        How many seconds to record? 0 means forever (default: 0.0)


$ recs control --help
usage: recs control [-h] {instances,status,disk,devices,capabilities,mutable,get,set,mark,pause,play,stop,pause-playback,continue,jump,jump-session,resume,calibrate,card-replace,reload-profiles,project-switch,musician-add,musician-list,musician-edit,musician-delete,musician-assign,musician-remove}

Send one command to a running recs instance.

 options
 ------------------------------------------------------------------------------------------------
  -h, --help           show this help message and exit

 subcommands
 ------------------------------------------------------------------------------------------------
  (required)
    - instances        List running instances without selecting a target.
    - status
    - disk
    - devices
    - capabilities
    - mutable
    - get
    - set
    - mark
    - pause            Pause capture and release input devices; this is not a playback pause.
    - play             Play a recorded session, temporarily pausing capture if it is active.
    - stop             Stop playback; restore capture only if playback owned the capture pause.
    - pause-playback   Pause playback without resuming capture.
    - continue         Continue paused playback, not capture.
    - jump
    - jump-session
    - resume           Resume capture, first stopping any active playback.
    - calibrate        Calibrate selected source channels, such as x18:1-2,5,6.
    - card-replace
    - reload-profiles  Reload per-device JSON defaults from --profiles, not a recording project.
    - project-switch   Switch mutable configuration to a named project or the default workspace.
    - musician-add
    - musician-list
    - musician-edit
    - musician-delete
    - musician-assign
    - musician-remove


$ recs daemon --help
Usage: recs daemon COMMAND [recs options...]

Commands:
  install      Install and start the per-user background recorder.
  uninstall    Stop and remove the per-user background recorder.
  start        Start the installed background recorder.
  stop         Stop the installed background recorder.
  restart      Restart the installed background recorder.
  status       Print daemon installation and running status as JSON.

Install stores the remaining arguments and runs recs with --silent.


$ recs edit --help
usage: recs edit [-h] STR [[STR [STR ...]]]

Run a named edit recipe or TOML file. Use COMMAND --help for its options.

Use compose COMPOSITION.toml to combine recordings into a composition.

 positional arguments
 ----------------------------------------------------
  STR                command (required)
  [[STR [STR ...]]]  arguments (default: )

 options
 ----------------------------------------------------
  -h, --help         show this help message and exit


$ recs explain --help
usage: recs explain [-h] [{None}|PATH] [--json | --no-json]

Explain recording diagnostics from a journal, or from the running daemon.

 positional arguments
 ----------------------------------------------------
  [{None}|PATH]      path (default: None)

 options
 ----------------------------------------------------
  -h, --help         show this help message and exit
  --json, --no-json  (default: False)


$ recs mute --help
usage: recs mute [-h] [--clear | --no-clear]

 options
 ------------------------------------------------------
  -h, --help           show this help message and exit
  --clear, --no-clear  (default: False)


$ recs preflight --help
usage: recs preflight [-h]

 options
 ---------------------------------------------
  -h, --help  show this help message and exit


$ recs project --help
usage: recs project [-h] {save,use,show,switch,list,delete}

Project files contain reusable configuration and track layouts. Musicians and assignments remain in mutable settings. These differ from the per-device JSON defaults loaded by --profiles.

 options
 -----------------------------------------------------------------------------------------
  -h, --help  show this help message and exit

 subcommands
 -----------------------------------------------------------------------------------------
  (required)
    - save    Save reusable configuration and tracks; musicians stay in mutable settings.
    - use     Start a recorder with a project's configuration and tracks.
    - show
    - switch  Switch a running recorder to a project, or omit NAME for the default.
    - list
    - delete


$ recs readiness --help
usage: recs readiness [-h] [OPTIONS] [[STR [STR ...]]]

Inspect project readiness; unlike preflight, no running daemon is required.

Put recording options after --. Missing devices warn; invalid settings fail. This command never opens input streams or performs the test-input recording.

 positional arguments
 ----------------------------------------------------
  [[STR [STR ...]]]  recs-options (default: )

 options
 ----------------------------------------------------
  -h, --help         show this help message and exit
  --project-name {None}|STR
                     (default: None)
  --json-output, --no-json-output
                     (default: False)


$ recs record --help
usage: recs record [-h] {check}

Validate recording documents and their media, not start capture.

 options
 ---------------------------------------------
  -h, --help  show this help message and exit

 subcommands
 ---------------------------------------------
  (required)
    - check


$ recs session --help
usage: recs session [-h] {show,quality,markers,extract,handoff,recover,recover-scan,finalize,export-midi,migrate,export}

Inspect or manage one session. Use recs sessions ROOT to list sessions.

 options
 ----------------------------------------------------------------------------------------------------------------------
  -h, --help        show this help message and exit

 subcommands
 ----------------------------------------------------------------------------------------------------------------------
  (required)
    - show          Inspect one finalized recording session.
    - quality       Report one recording document's evidence; audio decoding is opt-in.

                    Frame positions are source-local, half-open ranges, not cross-device alignment. Near-full-scale
                    advisories are not proof of clipping. No quietness verdicts.
    - markers       List numbered markers and their available source-frame evidence.
    - extract       Preview marker extraction; supply --destination to render a new session.

                    Use numbers from session markers, not labels. Select one capture clock. Without --end-marker,
                    lead/tail surround --start-marker. Durations are seconds. Historical unpositioned markers are
                    rejected, never mapped from wall time.
    - handoff       Preview aligned tracks from one sealed segment; --destination writes the bundle.

                    Frame bounds are half-open on one capture clock. No resampling or alignment between independent
                    clocks is inferred. Output is 32-bit float WAV plus JSON.
    - recover       Preview recovery of a stopped version 5 capture; --destination creates a copy.

                    Audio is fully decoded for verification. Unfinished readable audio is retained as unplaced assets,
                    not aligned tracks. No original files are changed.
    - recover-scan  Discover unfinished session records below ROOT once.
    - finalize
    - export-midi
    - migrate
    - export


$ recs sessions --help
usage: recs sessions [-h] [OPTIONS] [PATH]

Search recording documents and journals without decoding media.

Filters combine with AND. Text matching is case-insensitive substring matching. Results use path order; dates use the calendar date as recorded, not file times.

 positional arguments
 ------------------------------------------------------------------------------------------------------------------
  [PATH]                root (default: .)

 options
 ------------------------------------------------------------------------------------------------------------------
  -h, --help            show this help message and exit
  --json, --no-json     (default: False)
  --since {None}|YYYY-MM-DD
                        Inclusive capture date (YYYY-MM-DD); unknown dates do not match. (default: None)
  --before {None}|YYYY-MM-DD
                        Exclusive capture date (YYYY-MM-DD); unknown dates do not match. (default: None)
  --source {None}|STR   Source name or identity, including event sources. (default: None)
  --track {None}|STR    Source-qualified audio track name. (default: None)
  --marker {None}|STR   Journal marker label or pressed key. (default: None)
  --media {None,audio,midi,osc,key,ump,events}
                        (default: None)
  --incomplete, --no-incomplete
                        Only open recordings or recordings with unresolved audio placement. (default: False)
  --warning {None}|STR  Warning/diagnostic text; an empty string matches any warning. (default: None)
  --limit INT           Maximum matching sessions returned; unreadable entries still report errors. (default: 100)


$ recs test-input --help
usage: recs test-input [-h] [--include INCLUDE] [--seconds SECONDS] [--output OUTPUT]

options:
  -h, --help         show this help message and exit
  --include INCLUDE
  --seconds SECONDS
  --output OUTPUT

$ recs watch --help
usage: recs watch [-h] [----json | --no---json]

Watch a running recs instance.

 options
 --------------------------------------------------------
  -h, --help             show this help message and exit
  ----json, --no---json  (default: False)
