% dtas-splitfx(1) dtas user manual =head1 NAME dtas-splitfx - split audio and apply effects to all tracks =head1 SYNOPSIS dtas-splitfx SPLITFX_FILE.yml [OPTIONS] [TARGETS] [ARGS...] =head1 DESCRIPTION dtas-splitfx reads as YAML file and can apply effects (including resampling/dither), split, tag, and encode files in parallel. dtas-splitfx is intended for splitting recordings from vinyl and live concerts into separate files. dtas-splitfx is inspired by cuesheets for CD audio and the L build tool. dtas-splitfx primarily uses L, but it is possible to define targets to use L, too. =head1 OPTIONS =over =item -j, --jobs [JOBS] Number of jobs to run in parallel. If no number is specified, all jobs are run in parallel. Default: number of CPUS (dtas 0.20.0+), previous versions of dtas defaulted to 1. =item -n, --dry-run Print, but do not run the commands to be executed =item -s, --quiet, --silent Silent operation, commands are not printed as executed =item -S, --stats Add the sox "stats" effect to the end of the effects chain, use this with L to get a C<.stats> file with every track output =item -D, --no-dither Disable automatic setting of the DITHERFX env. This also passes the option to L via SOX_OPTS. =item -E, --err-suffix SUFFIX Write the contents of C. This is useful for capturing the per-track output of the L C effect when combined with parallel C<--jobs>. Recommended for use with the L switch. =item -O, --outdir OUTDIR Set output directory instead of current directory. User-created targets must allow a placeholder for the (by default, an empty string) $OUTDIR environment variable in the output command. =item -C, --compression FACTOR Set the compression factor passed to L. See L for more information on how it works across different formats. =item -r, --rate RATE Override the output sample rate in the specified TARGET =item -b, --bits BITS Override the output bit depth in the specified TARGET =item -t, --trim POSITION Passes a POSITION argument to the sox "trim" effect to allow limiting output to only process a portion of the original. This bypasses the "tracks" section and of the YAML file and outputs the result as a single file with the TRACKNUMBER of "000". For ease-of-typing, commas in this command-line argument are automatically expanded to spaces when passed to sox. This switch may not be combined with L =item -f, --filter [FIELD=]VALUE Only process tracks matching a given comment FIELD and VALUE. If no C<=> is exists, then all comment fields are matched against the specified VALUE. This switch may not be combined with L =item -p, --sox-pipe Used in place of an output target to specify outputting audio data in the native "sox" format to another L or L command. This moves printing of output to stderr and disables parallel job invocation. =back =head1 FILE FORMAT =over =item infile - string, the pathname of the original audio file =item env - hash of environment variables to set for all commands env: FX: gain 3 stats =item comments - hash of common tags for all audio (e.g. ARTIST, ALBUM, YEAR) comments: ARTIST: John Smith ALBUM: Hello World YEAR: 2013 =item track_start - integer, number to start the track count at default: 1 =item cdda_align - boolean, enforce sector alignment for audio CDs default: false =item track_zpad - boolean or integer Zero-pad the TRACKNUMBER in metadata and filenames. If an integer, this creates a fixed padding even if the padding is not necessary. If true, this only pads as needed for the highest-numbered track. Default: true =item tracks - array, see "TRACKS" section =item targets - hash, see "TARGETS" section =item command - override the default sox invocation This command may be used to specify an alternate command to process each track. Default: sox "$INFILE" $COMMENTS $OUTFMT $OUTDST $TRIMFX $FX $RATEFX $DITHERFX =back =head1 TRACKS Tracks may be defined by a start time, with the stop time defined automatically by the start of the next track, stop time, or a skip segment. =over =item t TIME TITLE [fade_in/fade_out=FADE_ARGS] [.FIELD=VALUE] [env.X=Y] The start of a new track at TIME with TITLE. An optional L and L may be specified for any tracks. Per-track comments may be specified in the form of C<.FIELD=VALUE>. Using per-track C<.ARTIST=FOO> allows proper tagging of multi-artist compilations. Per-track environment variables may be specified in the form of C where C is the environment variable name and C is its value. Per-track environment variables do not affect playback of YAML files via L nor use of the L command-line option. However, per-track environment variables do affect any tracks written to the filesystem, including those using the L switch. These environment variables are intended to affect the specified L or default L invocation. =item tshift TIME Increment subsequent time stamps for L, L, and L directives by the specified TIME offset. TIME can be prefixed by C<+=> or C<-=> to adjust the existing C value. Negative values can be specified by prefixing with C<-> for a backwards time shift. This directive is useful for working with multiple recordings of the same source and cutting a section from the middle of a recording after initial tracking is done. Default: 0 =item skip TIME - skip a segment starting at TIME "skip" segments are useful for skipping long gaps between tracks (such as flipping vinyl or intermission at concerts) =item stop TIME - stop the last track This should be the last directive in the "tracks" array. =back An example of the tracks array for a 4 track EP follows: tracks: - t 0:21 "This is the first track of an EP" fade_in='t 1' - t 7:11.6 "Second track of side A of an EP" - skip 9:18 # this is where I flip the record, comments are allowed - t 9:41 "3rd track of an EP" - t 13:36.5 "Final track of the EP" fade_out='t 1' - stop 18:11 =head1 FADES dtas-splitfx automatically sets up fade-in/fade-out effects for sox(1) based on track times. These are to be used in "t" (track) directives in the "tracks" array: =over =item fade_in="[TYPE] LENGTH" =item fade_out="[TYPE] LENGTH" =back TYPE is optional, but LENGTH is required. See L for a description of the fade type. =head1 ENVIRONMENT dtas-splitfx sets several default environment variables for commands to use in targets: =over =item INFILE - this matches the "infile" directive in the YAML file =item INDIR - the directory INFILE belongs to, without trailing slash =item INBASE - the basename of INFILE =item TBEG - the integer sample offset where the L trim effect starts =item TLEN - the integer sample count representing the length of the trim =item TRIMFX - essential Supplies the necessary L trim effect to each track. In other words, this is: "trim ${TBEG}s ${TLEN}s" =item COMMENTS - expands to --comment-file=PATH for L =item OUTDIR - placeholder for --outdir, defaults to an empty string =item SUFFIX - the suffix of the output format without "." (e.g. "flac", "ogg") =item TRACKNUMBER - the track number, useful for comments and filenames =item RATEFX - rate effect and arguments for L resampling =item DITHERFX - dither effect and arguments for L dithering =item FX - any user-specified sox effects which encompases the entire file. (e.g. "highpass 35 gain 3 stats") =back =head1 TARGETS The default targets will split audio and avoid applying any effects. They are named after common audio formats supported by L: =over =item flac =item ogg =item mp3 =item sox =back If not specified, "flac" is the default target. Additional targets supported by default. =over =item flac-cdda This encodes the audio to "flac" format while being easily decompressible to a format suitable for being burned to audio CD. =back Custom targets may easily be defined to apply effects and gain. For example, the following "flac24" target raises the volume of the left channel by 9.5dB and the right one by 8.5dB to compensate for channel imbalance in a live concert recording from the audience: targets: flac24: command: sox -M "|sox $INFILE -c1 -p $TRIMFX remix 1v1 gain 9.5" "|sox $INFILE -c1 -p $TRIMFX remix 2v1 gain 8.5" $COMMENTS $OUTFMT ${OUTDIR}bandYYYY-MM-DD.FOO.t0"$TRACKNUMBER.$SUFFIX" $RATEFX $DITHERFX stats format: type: flac bits: 24 rate: 48000 =head1 COPYRIGHT Copyright all contributors L License: GPL-3.0+ L =head1 SEE ALSO L, L, L, L