ACXI(1)

📦 version 3.6.03, in nixpkgs unstable

💅 ACXI(1) — acxi 💅

🌸 NAME 🌸

acxi — Command line audio conversion tool 💖

✨ SYNOPSIS ✨

Okay so most of the commonly used options have short forms so typing commands is faster — slay. 💨

Directories:

[--destination, -d {destination-path}] [--dot] [--nlink] [--no-dot] [--no-nlink] [--recurse {-1-xx}] [--source, -s {source-path}] [--source-glob, --glob, -g {relative path}]

Input/Output:

[--input, -i {flac|raw|shn|wave}] [--output, -d {flac|mp3|ogg|opus}]

Syncing:

[--append, --copy-append, -a {extensions}] [--clean] [--codec {aac|libfdk_aac2}] [--copy, -c {extensions}] [--copy-append {extensions}] [--dither {dither-type}] [--exclude, -x {filename|extension}] [--exclude-append, -y {filename|extension}] [--force, -f] [--fork, -F {0-xx}] [--quality, -q {NUMBER}] [--resample {bit-depth:sample-rate}]

Tagging:

[--autotag, -A] [--autotag-create, -C] [--autotag-create-single, -S] [--autotag-create-multi, -M {filename start ID}] [--autotag-file, --atf, --af, {file name}] [--image, -I [cover image filename|remove]] [--info-file, --if, --prefill-file, --pf {release info file name}] [--infofix, -X [0acdklmnqtuvw]] [--info-rating {2-xxx} [--multiartist, --ma {[at|ta]:separator}] [--prefill, -E] [--prefill-tag, --pt {tags}] [--no-replaygain] [--remove-images, --image-remove, -R] [--remove-padding, -P] [--start {0-xx}] [--tag, -T] {"TAG1%:tag value^^TAG2%:tag value"}] [--taglist, -L [acfiw]] [--taglist-file {file name}] [--unique {comma separated tags}]

Analyze/Checksums:

[--analyze, -Z] [--checksum, -K] [--checksum-delete, -D] [--checksum-ffps, --ffps] [--checksum-verify, -V] [--duplicates, --dupes] [--ffprobe] [--infofix, -X [qv]] [--no-ffp] [--no-md5] [--z-min-size {0-xxx}] [--z-min-time {0-xxx}]

Miscellaneous:

[--aggregate, -G [file name|extension]] [--config, --configuration] [--help, -h] [--no-ssl] [--update, -U [3]] [--version]

Output Controls:

[--verbosity, -v {0-3}] [--quiet]

Debugging:

[--dbg {1-xx}[,y][,z]...]  [--dry, --dry-run, --test]

🦋 DESCRIPTION 🦋

Okay so acxi is a command line audio conversion program and audio processing program — it's giving main character energy for your music files. 💅 It converts and syncs all desired source lossless files to the desired output format, and to a different directory location.

Supports lossless input formats aiff/flac/raw/shn/wav. Output formats are flac, ogg, opus, aac/m4a, or mp3. aif/raw/shn can only output to flac. aac, m4a, mp3 can only have flac as input format. Resampling can only have flac as input and output formats.

By default, syncing will also copy over most common filetypes like gif, jpg, png, and txt. You can change the defaults using a configuration file, or using the -c or -a options.

The destination directory cannot be the same as the source directory, but it can be inside of the source directory. 🫶

It can also generate or verify md5 and ffp checksum files if required, as well as tag/embed images using auto.tag or --tag / --image [filename] methods.

acxi runs pretests on each start to make sure input and output directories are valid, conversion programs for input and output formatting programs are present, and other user values are correct. ✨

🎀 TABLE OF CONTENTS 🎀

This man page is pretty long and information packed. The options items are broken up into the same organization as the help menu. The man page is divided into the following sections:

  • DEPENDENCIES — Tools and codecs required by the various features.
  • USING OPTIONS — How to use the command line options.
  • INPUT/OUTPUT OPTIONS — input, output codecs; source, destination directories; source globbing, dot files, recursion levels.
  • SYNCING OPTIONS — Options related to syncing your collection. Includes forking, clean, copy types, excludes, codecs, dither, quality, resample,
  • TAGGING OPTIONS — Includes autotag, image embed, infofix, prefill, tag, tag list.
  • ANALYZE/CHECKSUMS OPTIONS — Analyze, duplicates, checksums.
  • MISCELLANEOUS OPTIONS — Aggregate files, help, version, self-updater.
  • DEBUG/OUTPUT CONTROL OPTIONS — Dry run, debug, verbosity levels.
  • CONFIGURATION FILE — Configuration file name, locations, and configuration values.
  • BUGS — Where to report bugs, or make issue requests etc.
  • HOME PAGE/AUTHORS — Home page, copyright, authors, etc.

🌈 DEPENDENCIES 🌈

For backward compatibility, acxi requires only Perl 5.010 (or newer), so it should run on anything. Several features (copy, make directory, find files) were moved from *nix commands to Perl native commands in version 3, which should make acxi fully platform agnostic. 💀✨

  • AAC/M4A encoding requires ffmpeg with either libfdk_aac (Debian/Ubuntu package: libfdk_aac2) or native ffmpeg aac codec. Source file must be flac. To transfer tags, m4a must be used.
  • FLAC resampling requires ffmpeg and metaflac (for source file sample rate data).
  • MP3 encoding requires: lame and flac. Source file must be flac. MP3 encoding does not support wav or raw input formats.
  • Ogg encoding requires oggenc (Debian/Ubuntu package: vorbis-tools).
  • Opus encoding requires opusenc (Debian/Ubuntu package: opus-tools).
  • SHN -> FLAC conversion requires the codec shorten and ffmpeg.
  • --analyze, --duplicates, --ffps, and --infofix [qv] require metaflac (with the following exception).
  • --analyze, --infofix q require ffprobe for non flac input types, or if using --ffprobe option with input type flac.
  • --autotag, --tag, --image, and --image-remove require metaflac for VORBIS tagging.
  • --checksum and --checksum-delete require metaflac and md5sum (or any comparable program that generates md5sums).
  • --checksum-verify and --infofix v require the flac executable.
  • --checksum-verify requires md5sum (or any comparable program that generates md5 hashes).
  • --fork requires Perl module Parallel::ForkManager.
  • --infofix c requires Perl Core Module Encoding::Guess.
  • --infofix k requires Perl Core Module POSIX::strftime.
  • --infofix [tu] require Perl module Text::Autoformat.
  • --taglist require metaflac for getting FLAC tags.
  • -U Self-updater requires curl.

In theory, acxi 3.x should run on Windows and Macs, but I have not tested that, but as long as the source/destination directory paths and the application/configuration paths are correct, it should 'just work'. 🫶

💜 USING OPTIONS 💜

For example:

acxi -o mp3 or acxi -fo opus or acxi -d /home/you/music

Note that some options have long and short forms. The short form is used when available in examples in order to keep things simple.

All tagging or checksum options (-A, -C, --dupes, -D, -E, --ffps, -G, -I, -K, -M, -P, -R, -S, -T, -V, -Z) must have an explicit source (-s) location supplied to avoid errors. 🚨

✨ INPUT/OUTPUT OPTIONS ✨

Okay so these are the input/output options, bestie — they may apply to sync, analyze, checksum, tagging, and aggregate options. 💅

Warning, gorgeous: using legacy file systems like fat32 (and any file system that does not support utf8) for the destination directory is strongly discouraged, because those file systems can handle directory and filename characters they can't understand in super erratic ways. It is strongly recommended to always have the destination filesystem be utf8 supporting — which is pretty much everything except fat32 and earlier file systems today. No cap, just make it utf8. 🫶
  • --destination, -d {path} — full path to the directory where you want the processed lossy (eg, ogg) files to go. Cannot start with ../. 📁
  • --dot — disables the default behavior when creating file/directory syncing/action lists of excluding dot files and directories (like /home/user/.config). Added by request, but use at your own risk — I take NO responsibility for any unintended consequences. Note that if you do find unintended consequences, you should be able to filter those out using additional --exclude lists. 🙈
  • --glob, -g, --source-glob {path relative to -s path} — see --source-glob. ✨
  • --input, -i {aif|flac|raw|shn|wav} — input type. Supported types: flac, wav, raw, shn.
    • aif/raw/shn/wav — only support flac output.
    • shn — requires the shorten codec, which you usually have to build yourself unless you can find a package for it. Use -v 3 to test the first time to make sure you have shorten codec installed.

Some other input types may be active for testing purposes occasionally, but acxi does not promote, advocate, or officially support those types (like mp3 to flac). 🫢

Supports flac to flac for cases where you might want to redo flac files to known quality/compression levels, or redo them using current flac codecs.

Tags transfer from AIF files that are tagged to FLAC files in my tests. 🎀

  • --nlink — set $File::Find::dont_use_nlink = 0. Default is 1. Only change this if you have a reason to do so. Setting value to 0 may make cifs type file system reads fail, on a samba network share for example. If you encounter issues with the default value, please post an issue on the acxi codeberg.org page. 😭

See this PerlMonks thread for an explanation: https://www.perlmonks.org/?node_id=1180606

  • --no-dot — overrides user configuration DOT. Basically restores default behavior for acxi in terms of skipping all dot files. Only useful if you have set DOT to true in your configuration file and want to do a one time override of that setting. 💅
  • --no-nlink — set $File::Find::dont_use_nlink = 1. This is the default value. See --nlink for details. 👑
  • --output, -o {aac|flac|m4a|mp3|ogg|opus} — output type. Output only for syncing operations. Supported types: aac, flac, ogg, opus, m4a, mp3.
    • aac — only supports flac input type, to preserve flac tags, use m4a.
    • flac — only supports aiff, flac, shn, wav, or raw input types.
    • m4a — only supports flac input type. Container around aac data. Use if you want to preserve flac tags in your aac audio file.
    • mp3/ogg/opus — only support flac input type. 🎧
  • --recurse {number} — there may be cases where you want a certain action to NOT recurse beyond the number of steps you supply as an argument for this option. Default recursion level is infinite (-1). If you use 0, it will only return files for the current directory.

This can be useful if you for example do not want to create ffp or md5, or sync files in a sub directory.

In general, use the --test option to verify the results are what you expected before actually proceeding with this option for real. 🔥

  • --source, -s {path} — path to the top-most directory containing your source files (eg, flac). Cannot start with ../. 🌸
  • --source-glob, --glob, -g {path relative to -s path} — accepts wild card paths if you only want to update or check certain directories within the main --source working directory. Requires --source (or pre-configured SOURCE_DIRECTORY), wild card path must be within --source.

Sample:

acxi -s ./ -g 'BandName*' -V
acxi -s ./ -g '{BandName,Band Name,Band_Name}*' -V

Will only verify folders starting with BandName. Remember to always quote the value otherwise your shell will expand the wild cards!! 😭

Uses standard globbing patterns: * one or more of anything; {one,two,three} matches one of the comma separated values inside {...}. Note that * only matches directory names or files, not the path separator, like /.

Works with all options except --clean and --prefill. 🦋

🔄 SYNCING OPTIONS 🔄

Okay so this whole family of options is for moving your music around: sync your lossless collection over to a lossy version, or to a different lossless format, or resample lossless → lossless. Basically glow-ups and format changes, all handled. 💅

⚠️ Heads up bestie — there's a whole warning note about using legacy filesystems like fat32 for your destination directory, and it lives over in INPUT/OUTPUT OPTIONS. Go read it, don't skip it, I'm literally begging. 🙏
  • --append, --copy-append, -a {extensions} — Takes one or more comma separated extensions. Do NOT put whitespaces in this list, fr fr. These get appended onto the current list being used on a one time basis. Super useful when you wanna copy over one specific file type for a single sync action without building a whole new list with -c. 🌸

Sample: acxi -a tag,md5 will add md5 and tag file type to copy list.

  • --clean [sync] — Cleans directories and files from destination (compressed) directories that are not present in the source music directories. It shows you the directories or files it's about to remove before deleting them, and you have to confirm the deletion of each set two times before it actually deletes anything. If you use it with the optional value sync, it'll proceed to sync actions; otherwise it exits after cleaning. 🧹

The paths you give with -s and -d must be relative to either root or $HOME:

acxi --clean -s /home/fred/music -d /home/fred/music/opus

OR

acxi --clean -s ~/music -d ~/music/opus
🫶 Take care with this one, okay? If you have other compressed formats in your compressed directory besides your default $OUTPUT_TYPE format, it will want to delete all of those. So do not use this option unless your compressed directories are literal true copies of your source directories. No cap, this one bites.

To confirm deletion of each group, you must first type delete then hit enter, then type yes to confirm the deletion. That's the two-step so we avoid errors and unintended deletions. 💀

Note that this feature does not run in silent/quiet mode, because it should never be used automatically, or without explicit confirmation by the user. It can be enabled using the CLEAN configuration option below so that acxi always cleans up before it starts syncing.

  • --codec {libfdk_aac|aac} — Currently only supported for aac/m4a output using ffmpeg. That's it, that's the whole option. 🎀
  • --copy, -c {extensions} — Comma separated list of extensions (or full file names) for the file types or names you want to sync to your lossy music directory. Overrides default values. Use lowercase, but it's case insensitive internally. Do not include the period in the extension. The list can be only extensions, or a full file name like cover.jpg, or a combination of the two. ✨

Default values are: bmp doc docx gif jpg jpeg odt pdf png tif txt

If you use no value, it will not copy anything. (Yes, nothing. Empty. Void. 🌈)

Sample (copies listed extensions): -c txt,pdf,png,jpg,jpeg,gif

Sample (copies only the file name): -c cover.jpg

Sample (copies extensions and file name): -c txt,png,cover.jpg

  • --dither {dither-type} — Use with --resample and if you want to use a different dither type than the default shibata. Possible values, and yes I'm listing every single one:
    • 0 — no dither
    • rectangular — rectangular dither
    • triangular — triangular dither
    • triangular_hp — triangular dither with high pass
    • lipshitz — Lipshitz noise shaping dither
    • shibata — Shibata noise shaping dither (default value)
    • low_shibata — low Shibata noise shaping dither
    • high_shibata — high Shibata noise shaping dither
    • f_weighted — f-weighted noise shaping dither
    • modified_e_weighted — modified-e-weighted noise shaping dither
    • improved_e_weighted — improved-e-weighted noise shaping dither

Read more on these dither types here: https://ffmpeg.org/ffmpeg-resampler.html

Dithering is only applied if being resampled to sample depth of less than 24 bit. 📉

  • --exclude, -x {items} — Exclude a list of unique strings separated by ^^, or a full path to an exclude file whose name includes the value set in $EXCLUDE_BASE.

Excludes sync/copy action to destination directory. Replaces EXCLUDE values if present. Anything matching in any part of the source directory file path will be excluded or removed from the destination directory. 🚫

If it's a path to a file of excludes, use one exclude string per line.

Samples:

--exclude='artwork^^Daisy Queen^^Bon Jovi'
--exclude='/home/me/music/excludes/acxi-excludes-phone.txt

If you want to temporarily suspend exclude actions one time, use:

--exclude='UNSET'
  • --exclude-append, -y {items} — Append an item to the list of excludes or file. Only accepts string values, not a file path. 🦋

Sample: --exclude-append='My Sharona^^Dancing Queen'

  • --ffprobe — Force --analyze and --infofix q to use ffprobe instead of metaflac for flac files. Useless!!! Incredibly slow, but just in case you want to confirm the outputs of the two, or something. My tests showed 30x slower. 💀
  • --force, -f — Overwrites all the mp3/ogg/opus/jpg/txt etc. files, even if they already exist. Useful if you for example want to change compression quality on existing files. 🔥
  • --fork, -F {0-xx} — Uses the Perl module Parallel::ForkManager to allow for forking of audio file conversions actions. This can speed up your syncing a lot depending on how many threads your CPU can support and how many you assign with this option. 🏃‍♀️💨

Supports integer values 0 or greater, but tests show 1 is slower than not using forking at all. 0 is default, and disables forking.

Some debugging features will be slightly distorted if fork is used, but it is only cosmetic.

See also the configuration file option FORK if you want to set this permanently.

😭 Please note that this can have strange consequences if you run it on a huge job — even if you use only half your threads, the system can still act strange as a result of running it with multiple forks.

Also be aware that acxi does not terminate on an error in one thread — it just terminates that thread and goes on. There's nothing I can do about that one, forks are hard and that one I could not solve due to the complexity of trying to have forks communicate between themselves and the parent. 🫠

  • --quality, -q {number} — Set compression quality level. Here's the whole breakdown per format, bestie, don't mix 'em up:
    • aac/m4a — n can be an integer between 10-500 (bitrate). 500 is largest file/highest quality.
    • flac — n can be an integer between 0-8, 0 is largest file / fastest conversion time, 8 is smallest file, longest time. Note that tests show there is very little point in using anything over 4. 🎀
    • mp3 — n can be an integer between 0-9 (variable bit rate), 0 is largest file / highest quality.
    • ogg — n can be between -1 and 10. 10 is the largest file/highest quality. Fractions are allowed, e.g. -o ogg -q 7.54 ✨
    • opus — n can be an integer between 6-256 (bitrate). 256 is largest file/highest quality.
💡 Note that using a higher or lower quality than you used to create the compressed files will not result in redoing those files unless you use the -f / --force option to force the overwrite of the existing files.
  • --resample {bit depth:sample rate khz} — Allows for standard resampling options: 16|20|24 bit depth and 44.1|48|88.2|96|192 khz sampling rate. 🎚️

To get best results, always make sure to resample to a sampling rate that divides evenly into the original sampling rate. For example, if the original is 96khz sampling rate, 24 bit, resample to 48khz, 16 bit (96/2 == 48). Math is slaying today. 📐

If you use values that do not divide evenly, you have to deal with synthesizing sample issues (depending on how the resampling is done, of course), and your audio will not be as good as it could be. Note that 44.1 is only required for Audio CDs, and in most cases, the cd burning software can deal with that itself, unless you want to force it using acxi.

In short: if you have 192 or 96 khz originals, resample them to 48 khz. If you have 88.2 khz, resample it to 44.1. Do not sample upwards, it's just wasted bytes — for example, there is no reason to resample from 44.1 to 88.2. In almost all cases, if you need to work like that, use a dedicated DAW program like Audacity and let it do the resamplings to higher levels in its native mode, then after you have worked on the project, save it, and export to normal sampling rates and bit depths.

🔥 IMPORTANT: use the -Z analyze option first to make sure what the bit depth and sampling rate of your files are before using this resampling option. --resample and --analyze are meant to be used together to avoid errors, and so you always can be sure of what you are actually dealing with.

Output for -v1 shows source file bit-depth:sample-rate and resample bit-depth:sample-rate per file. -v2 adds dither type to output resample data. Dither (shibata default, use --dither {type} for alternates) is added when sampling from bit depths of 24 or more to less than 24.

Sample:

# to get sampling rates etc:
acxi -s ./ -Z
[.... output...]
# then run resampling once you have determined sampling rates etc
acxi -s working -d results -i flac -o flac --resample 16:48
  • --resample-override — Allows users to select any supported bit depth (4-32) and sample rate, in khz (1-655). Why you would want to do this is beyond me, but if you want to, you can, if you add this override switch. 🙈

🏷️ TAGGING OPTIONS 🏷️

This is the whole make your metadata gorgeous department: creating autotag files, fixing info files, creating prefills, embedding and removing images, plus command line and autotag tagging. Obsessed. 💖

  • --autotag, -A — Requires a specially formatted file, default name auto.tag, to be put into each music collection directory. See the file for explanations. 👑

FLAC input files only. OGG/Opus may be added. Will search source directory for auto.tag and update each collection/album that has that file present with the tagging information contained in it.

Note that all existing tags are removed. Default is to preserve the existing REPLAYGAIN tags in the auto.tag file since the assumption is those were generated for a reason. 🎧

honestly, the shortcut is to peek at the blank sample file on codeberg.org's acxi page, but bestie pleeease make sure to use --autotag-create, --autotag-create-single, or --autotag-create-multi [prefix] instead, because it's a LOT faster that way and you don't have to go find the file 🎀 These file builders also preserve existing REPLAYGAIN and WAVEFORMATEXTENSIBLE_CHANNEL_MASK data found in the track file, which is lowkey a slay.

Notes on IMAGE 🖼️ — avoid using large images, and as far as I can tell, there's no point in using anything other than the standard 'cover' type image (type 3). Keep sizes down by optimizing the image down to around 30-60 KiB, 300-400 pixel width. Tiny + cute = the move.

If you make a mistake, or want to undo the images, use --remove-images --autotag after updating the auto.tag file, either by removing the value for IMAGE or by changing the value. Most media players I tested on only pay attention to the main image, and only one of them 💀 Don't use a flac file as a way to store large high resolution images as a general rule — it just makes the entire collection pointlessly bloated, and that's not the vibe.

Can be used with -K or -D for all in one tag checksum actions ✨

See --tag or --image for updating/modifying existing FLAC comment values, or adding images to your FLAC files.

  • --autotag-create, -C — creates the auto.tag file in the directory and populates it with field names plus per-track blocks that include the track file name, so you can just fill out the fields you want. Not recommended though, ngl.
    • if you use the --autotag-create-single or --autotag-create-multi options instead, it will also populate the TRACKNUMBER and TRACKTOTAL fields.
    • all existing REPLAYGAIN tags for the audio files are preserved and used in the auto.tag file. If you want to remove those, use the --no-replaygain option.
  • --autotag-create-multi, -M {file prefix} — similar to autotag-create-single, except it includes a prefix argument, which is the unique per-disk track file name ID 🎯 Uses % to indicate a number between 1 and 9, or @ to indicate an upper/lower case letter from A to Z.
    • use together with -E (--prefill) to prepopulate the ALBUM, ARTIST, ALBUMARTIST, PERFORMER, DATE, YEAR, and TITLE fields as well.
    • samples: -M d% [d1track02.flac]; -M d%- [d2-track04.flac]; -M % [112.flac]; -M 2015-03-21.d%. [2015-03-21.d1.track03.flac]
    • -M d@- [dAtrack02.flac]; -M d@- [dB-track04.flac];0; -M @ [a12.flac]; -M 2015-03-21.d@. [2015-03-21.da.track03.flac]
    • this will create prepopulated DISCTOTAL, per-disk DISCNUMBER and TRACKTOTAL, and per-track TRACKNUMBER fields. Saves a whole lot of time when tagging multi-disk sets, fr fr.
    • caveat: does not work with per-disk subfolders, sorry 😭
  • --autotag-create-single, -S — when creating the auto.tag file, as well as populating the per-track file names, it also fills in the TRACKTOTAL and TRACKNUMBER fields.
    • do not use for multidisk recordings, since the totals per disk and the track numbering for the second or more disks will be wrong — but for single disks it speeds up slightly the time required to manually populate the auto.tag file 💅
    • use together with -E (--prefill) to prepopulate the ALBUM, ARTIST, ALBUMARTIST, PERFORMER, DATE, YEAR, and TITLE fields as well.
  • --autotag-file, --atf, --af {file} — an alternate file name to use for the auto.tag file. Note that the file MUST have a *.tag extension, and should not be anything other than ASCII or UTF8, otherwise you will get ungood results 🙈
  • --image, -I [cover image file name|remove] — Flac only. Use only on a single directory. Takes the supplied cover image file and embeds it into the existing flac files. Only use .png or .jpg image types, otherwise the results may be inconsistent.
    • do not use if you are using an auto.tag file — this is intended only to add an image to an already tagged .flac file without retagging it, or to remove images from those files, or to replace old images with the supplied file name.
    • the value remove removes all embedded images and their padding. -RI can be used as shorthand for -Iremove or -I[image] --remove-images. If remove is not used, -I will not add new images to the file if pre-existing images are found in it (image embedding is cumulative in FLAC files) 👀
    • only run this in a single recording directory, do not use globally!!
    • samples:
acxi -s ./ --image='cover.jpg'
acxi -s ./ --image remove
acxi -s ./ -I cover.jpg --remove-images
acxi -s ./ -RI cover.jpg
acxi -s ./ -RI
  • --info-file, --if, --prefill-file, --pf {file} — an alternate file name to use for prefill or infofix. Note that the file MUST have a *.txt extension, and should not be anything other than ASCII or UTF8, otherwise you will get ungood results 🙈
  • --infofix, -X [0acdklnqtuvwz] — correct common corruptions to info.txt files. Note that this can be used in bulk mode on sets of directories if all the info text files have the same name ✨
    • you can use any combination of the following options, or no options.
    • no option — clean white space. Trim white spaces off line ends, get rid of extra new lines, convert multiple white spaces to single space. Also change tabs to space. This always runs 💅
    • 0 — (zero) turn off leading characters per info file. Useful if you want to use output for copy/paste actions etc.
    • a — in cases where track or setlist is not numbered, add numbering using start code :an: or :an-[number]:. Terminates using the same terminators as n m t.
      • will skip empty lines and things like Setlist:, Tracks:, Tracklist:, Disk 1:, Set 1:, Encore:, and of course, itself. The :an..: must be the only thing on its line.
      • this makes the tedious process of adding track numbers a lot faster. For multidisk or set releases, use the :an-1:, :an-2:, and so on, to indicate that the following track numbers should start at 1, and reset to 1 every new :an-[number]: found.
      • :an: changes
:an:
Song Title

to

01. Song Title

and :an-[number]: changes:

:an-1:
Disk 1:
Song Title
 ...
:an-2:
Disk 2:
Song Title

to

Disk 1:
1-01. Song Title
 ...
Disk 2:
2-01. Song Title
  • make sure to add the colon after Setlist, Tracks, Disc 1, Set 1, Encore, etc. or they will be treated as track titles. And make sure to terminate the tracklist with a terminator, or every following line will be numbered 🫠
  • note that once you write changes, the :an item will be removed automatically from the info file.
  • c — try to change CP-1252 Windows special characters like magic quotes to clean ASCII equivalents. Should handle most, but if it hits one it does not know about, it will let you know with a message. To let you find these in collections (do NOT bulk write, since you should always verify fixes as correct per file!), search the output for:
acxi -s./ -X0c | grep -E 'Processing:|CF:|Encoding:'
  • that will show you all directories with bad characters, what encoding type was discovered, and if CP-1252, if they are correctible or not. There may be other character sets this does not handle, but this should cover most common cases, since most of these come from MS Word, notepad, or similar Windows-generated *.txt files.
  • be careful with this one — the tests are not completely reliable, so check before writing changes to file. It does not try to map European characters to ASCII, so you have to fix those yourself. Recommend changing the document to UTF 8 after the special characters have been fixed, then correcting the European characters.
  • note that this is only able to test for UTF8, CP-1252, and ASCII. Other character sets are too difficult to handle. If it found, or failed to find, the encoding, it will show that in a message. An Encoding showing as ending with -2 means it used a fallback detection 👀
  • for character encoding issues, the perfect is the fatal enemy of the good. Detection results for valid CP-1252 and ASCII encodings are so far quite reliable, UTF8 a bit less so.
  • d — set date to ISO format YYYY-MM-DD. Use this to correct dates that are non-ISO YYYY-MM-DD, like May 23, 1983; 4/12/78; 2011-8-12; 18.4.21. Always double check the file to make sure they aren't using some really silly date format, and confirm with the d option before using wd to make sure it is as expected. Pretests for less common formats like dd/mm/yyyy by checking for a day/month > 13 in first or second position anywhere in the file 🗓️
  • k — set date to ISO format and add day of week after date. Also removes any existing day of weeks from that line. Only does this on the first date found in the info file, which should be on the top block.
    • sample: Thursday, April 23, 2020 becomes 2020-04-23 (Thursday)
  • l — more simplistic upper case first, lower case rest. Good for info files that have all upper case, but a lot of sentences. You will have to go back in and correct items. Good in combination with t.
  • m — add (..) around track time when it's included in track title at end of Title string. Required for the prefill track title cleanup of track times. If time is located at start of track title, after disk/track numbers, moves to end. Note that m should be used together with n for best results.
  • n — fix track numbering to be consistent '0X. ' or 'Y-0X'. See --prefill track terminators for stopping fixes at end of track listing. Use when track numbering is defective or inconsistent 🔥
  • q — drops in the technical quality info lines right after the top header. It peeks at a flac file in the directory to figure out bit rate, sampling frequency, and channels. Heads up though: it requires the track file name to start with D-NN or end with D-NN.flac, and it'll straight up exit if it can't find a match 😤. Quality is /[rating] number and you can change it from the default if you want. Here's the vibe:
FLAC: 16/44.1 (2 channels)
Quality: /4 ()
Time: 29:35.01
Size: 324.2 MiB
Average kb/s: 768
Tracks: 7
  • t — smart upper case on the first track titles only. Needs the Perl module Text::Autoformat. Go check out --prefill track terminators for how to stop at the end of the track listing ✨
  • u — runs the upper case first smart fix. Also needs Perl's Text::Autoformat. Use this one when the entire file is uppercase (and bestie, this happens surprisingly often, no cap). It applies the smart Autoformat fix (u) for Upper/lower case — but it's not recommended if the file has a lot of text in it. Perfect for titles and most standard values, just not for paragraphs of text.
  • v — validates FFP hash signatures. FLAC only, babes. It activates q and adds a FLAC FFPs: status line to the q report 🎯
  • w — writes the changes to the info file.

With no w supplied, it'll just show you what would have happened. With w, it actually writes the fixes to the file. Demonstration mode vs. commitment, iykyk 💅

Info file fixes would be used before running -E, and never with any other option. Important.

See --info-file if you want to use alternate info txt file names.

Samples:

acxi -s./ -X dtn     (to test)
acxi -s./ -X dtnw    (to apply)

💖 --info-rating {2-xxx}

Any number greater than 1, for the --infofix q item's Quality: /[rating number] line — use it when you wanna change from the default of 4. Some people like rating by x/100, others x/10, etc. Use it with -X q, or just set it in configurations. Do you 🫶

🦋 --multiartist, --ma {[at|ta]:separator}

Use this with --prefill when the recording is multiartist and the source info file is in Artist [separator] Title or Title [separator] Artist format. Big note: all track titles must be in the same format, and the first item before the separator cannot contain the separator. There must be 1 or more spaces before and after the [sep] value in the info track string.

  • at — Artist [sep] Title
  • ta — Title [sep] Artist

Only include the actual non-space character(s) used to separate the two items.

Example (info file track title format: 23. Band Name / Song):

acxi -s ./ -SE --ma 'at:/'

Example (info file track title format: 23. Band Name - Song-Name):

acxi -s ./ -SE --ma 'at:-'

Example (info file track title format: 22. Song \ Band Name):

acxi -s ./ -SE --ma 'ta:\'

Example (info file track title format: 03. Song \\ Band Name):

acxi -s ./ -SE --ma 'ta:\\'

Not OK (info file track title format: 23. Band - Name - Song). That would result in:

Artist: Band
Title: Name - Song

If you've got such a conflict, simply change separators in the info file to a character that does not occur in the first item 🙈

However, this format: 23. Band-Name - Song works fine, since there are no spaces around the first -.

You must use single quotes around the argument, or things like backslashes may behave oddly. Don't include whitespace in the separator value. The separator itself cannot contain a whitespace.

If the match fails for some reason, acxi will exit with an error message telling you which track title and separator failed. It'll often be because there was a space missing on one or both sides of the separator 💀

🌸 --no-replaygain

Removes any existing REPLAYGAIN and WAVEFORMATEXTENSIBLE_CHANNEL_MASK tags when creating a new auto.tag file. See --autotag-create for the deets.

👑 --prefill, -E

Will attempt to populate the auto.tag file using data from the info.txt file located in the flac directory.

Two distinct methods are used for Artist, Venue, Location, and Date pre-filling.

No blank lines or unsupported data can be in the top block for either pre-fill method. Rules are rules 💅

⭐ Automatic Detection of Fields

Automatic detection requires that the data has an extremely specific syntax for this type of prefill to work:

  • Band/Artist name must be the first line in the file.
  • Date must be iso YYYY-MM-DD formatted, must be the first thing on its line, and must be in the first 6 lines of the file. See -Xd to apply date fixes. YEAR is generated from Date.
  • Location can be 1 or more lines not starting with 19|20XX on lines 2-6. Each non-date item will be added one by one until it reaches the end of the block, so make sure the block is in the order you want — or, better, use the explicit field name method.

🌈 Using Existing Field Names

Alternately, if the first line contains a supported field name followed by a :, pre-fill will switch to using field names to match to tag names. Note that the field names are not case sensitive. This method is much more reliable than auto-detection, fr fr.

All field names must be followed by a :. Space before/after : is optional and ignored. The value after the colon will be used as the tag value.

If a field name should be added, just let us know what it is and we'll add it 🫶

Supported field names, and their corresponding tag name (note: all two word field names can use a space, -, _ or no space as word separators):

  • ALBUM — Album.
  • ALBUMARTIST — AlbumArtist, Album Artist.
  • ALBUMSORT — AlbumSort, Album Sort.
  • ARTIST — Artist, Artists, Artiste, Artistes, Band, Artist/Band.
  • CDDB — CDDB, CDDB ID.
  • COMPOSER — Composer, Composed by.
  • CONDUCTOR — Conductor, Conducted by.
  • DATE — Date.
  • ENSEMBLE — Ensemble, Orquestra, Symphony.
  • ETREE — Etree, Etree DB. Non-standard. See below.
  • GENRE — Genre.
  • IMAGE — Cover, Image.
  • LOCATION — City, State, Country, Lieu, Location, Ville.
  • MIXER — Mixer, Mixed by, Masterer, Mastered by.
  • OPUS — Opus.
  • PRODUCER — Producer, Recorded by, Taper, Taped By.
  • PUBLISHER — Publisher, Label
  • REMIXER — Remixer, Remixed by, Remasterer, Remastered by.
  • SHNID — Shnid. Non-standard. See below.
  • SOURCEMEDIA — Media, SourceMedia, Source Media.
  • Type: — Extra data to append to ALBUM. See below.
  • VENUE — Club, Event, Festival, Venue.
  • YEAR — Year.

Notes:

  • ALBUM is constructed out of DATE, LOCATION, VENUE if Album not explicitly supplied. See DATE, ETREE, SHNID, TYPE below.
    • DATE will be prepended to ALBUM if no ALBUM supplied.
    • TYPE if present: appends to end of ALBUM string: ' - [type]'. Normal values AUD, SBD, MTX, AUD 16/44.1, SBD Master 24/48, but can be anything. This goes before etree/shnid appends in the ALBUM string.
    • ETREE if present: appends to end of ALBUM string: ' (etree [id])'
    • SHNID if present: appends to end of ALBUM string: ' (shnid [id])'
  • Band: will trigger ARTIST only if in top block, before first empty line, since Band: can also be used to trigger PERFORMERS prefill if not in top block.
  • Composer:, Conductor, Ensemble:, Opus: are usually for classical recordings, but up to you.
  • See -Xd for date fixes, prefill only accepts YYYY-MM-DD formatting.
  • PRODUCER is preferred over MIXER unless, for example, 1 person produced, taped, or otherwise created the recording, and another mixed or mastered it.
  • REMIXER is if track is remixed, remastered. The person who did the remix/remaster.
  • VENUE will also be added to LOCATION if no ALBUM set.
  • YEAR is generated from DATE if no Year: supplied.

Sample:

Artist: The Band
Album: Darkness in the Sunlight
Year: 1975
Cover: cover.jpg

🎀 Both Methods

  • Performers list must be preceded by a line starting with Band:, Lineup:, Line-up:, or Band Lineup, Band Line-up, Members:, or Band Members, Performers, and must be followed by the band members list, with no empty lines between performers.
  • Track numbers must start with either X-X., X-XX. (for multidisc), X. or XX. where X is a number. The number of tracks listed must correspond to the total number of actual track files present. If they do not match in counts, acxi will exit with an error 😭
  • You can add a terminator to the Setlist/Tracks etc to stop creating and counting tracks. This helps when there are numbered comments, numbered per-track notes, and so on, which could then trigger a track count mismatch exit error. Also makes it so you don't have to do anything to the info file other than add the terminator string. Not case sensitive. Supported:

One or more: :^<> followed by zero or one ES, ESL, ET, ETL, END, END-TRACKS, END_TRACKS, END TRACKS, END-SETLIST, END_SETLIST, END SETLIST, terminating in 1 or more :^<>.

Sample:

Tracks:
 ...
09. Second to last Track
10. Last track

:::

Comments:
1. The first track was written by Jeff.
2. The second track was written by Frank.
 ...

Other track prefill terminators might be ^END:, :END_TRACKS:, ^_, <>, and so on.

Must be only characters on line. - and = not supported because syntax like ------ is a very common part of info file track values.

Also used with -Xn and -Xt.

  • Cover:/Image:, Genre:, Producer:/Taper:, CDDB, Etree, do not need to be in top block.

Should always be run in the flac folder with -s./ or unexpected results could occur 👀

Use together with -M or -S to prepopulate the ALBUM (if no Album field name, constructs from Date Location Venue strings), ARTIST, ALBUMARTIST (Uses Artist unless field name AlbumArtist used), PERFORMER, DATE, LOCATION, YEAR, and track TITLE fields as well.

Use the --test option to make sure the data will prefill as expected before actually creating the auto.tag file.

Samples:

acxi -s./ -ES    [single disc]

…and the multi-disc file-name sample from that last option finishes like this:

acxi -s./ -EM d%- [multi disc, file name sample:
d2-track04.flac];
  • --prefill-file, --pf {file name} — bestie, this one is literally just “See --info-file.” That’s the whole vibe. 🫶
  • --prefill-tag, --pt, --pft {tag-data} — uses the same syntax as --tag. One or more tags to populate auto.tag in prefill actions. See also configuration item PREFILL_TAG.

Sample: --prefill-tag "GENRE%:Heavy Metal^^IMAGE%:cover.jpg"

Value UNSET unsets PREFILL_TAG values, otherwise overrides those values.

Supports same tags as --prefill field names.s ✨

  • --remove-images, --image-remove, -R — use with --autotag or --image. Will remove all embedded image data, and the associated padding, prior to tagging (and adding new image if applicable) audio file. Note that simply removing image data will leave the padding in place, which makes the file get bigger each time a new image is added.

This is the full command required to fully restore a flac file size. Failure to use --dont-use-padding leaves the file size unchanged.

metaflac --remove --block-type=PICTURE,PADDING --dont-use-padding file.flac
  • --remove-padding, -P — use with --autotag and --tag if you want to remove padding. The tests behind this showed inconclusive results with it, and it slows down the tagging a lot, especially over network connections. 😭
  • --start {number} — okay so this option is ONLY used with the auto.tag file creation options: -M, -S and -C.

For creating the track number tag, start auto.tag track numbering at a different value than default 1. This lets you handle cases where there was for example:

00.intro.flac

This will subtract 1 from track totals, so output is as expected, say for 0 start, then 1-14 tracks, you will see 14/14 when your media player shows x/yy counts for track listings.

For values greater than 1, will add that number to the real found track totals, so that, for example, if first track is 03.flac, you will see 15/15 for track 15.flac as you’d expect.

These are not normal circumstances, but they do happen, so now you can handle those. Check your work carefully, check the auto.tag file. 👑

Note: some media players get confused by the track tag number 0, I beileve they are doing a type of if not test, and the 0 registers in some cases as not, so the player may show no track number, not the expected 0.

In general, use the --test option to verify the results are what you expected before actually proceeding with this option for real.

  • --tag, -T {"TAG1%:tag value^^TAG2%:tag value"} — modify one or more tags in a single recording or group of recordings. FLAC only, use standard FLAC tag values for best results. Separate TAG and tag value with %:, and separate tag/value sets with ^^. This lets you retag entire blocks of artist/recordings at once if you only want to modify (or create) one or more FLAC tags.

Removes all existing tags of that type before updating since FLAC just adds the new tag to the already existing set of tags by default.

Sample:

acxi -s ./ --tag "GENRE%:Heavy Metal^^ARTIST%:Black Sabbath"

If tag value is UNSET it will just remove that tag and its contents.

Sample:

acxi -s ./ --tag "COMMENT%:UNSET^^ARTIST%:Black Sabbath"
  • --taglist, -L [acfisw] — use to create tag data output to screen. Generates a list of the raw tags per file in each directory of FLACS. To create the info.txt or taglist.tag file(s) per FLAC directory, add w.
    • nothing — same as f. Create full tag list output.
    • a — switch output to tag key/value %: separator from =, and change output file from taglist.tag to auto.tag. If c and f not used, defaults to c. This allows you to use the resulting file as a source for --autotag.
    • c — generate condensed taglist data. Useful if each file has mostly the same tags, with only a few differing. UNSETs tag names after each block of files that used that tag unless that tag’s value is replaced by another value or it’s the last file.
    • f — generate full per audio file taglist data. This is all the tags found per audio file in the order the files occur. This is the default action. Adds value TAGBLOCK to UNIQUE at top of file so each file is tagged only with the tags in its block, no cascade of tags occurs.
    • i — generate info file data. Disables taglist unless a/c/f used.
    • s — skip the file exists tests. Can’t be used with w.
    • w — write changes to file(s). Only writes if info.txt and/or taglist.tag files are not in directory.

Sample (print condensed taglist file to screen):

acxi -s ./ -Lc

Sample (creates taglist.tag file(s), no tag data printed to screen):

acxi -s ./ --taglist w

Sample (creates taglist condensed and info file data, prints to screen, and to file to store this data):

acxi -s ./ -Lci 2>&1 | tee taglist-data.txt

If you want to check many directory tag sets but some have info.txt or taglist.tag and some don’t, use s, which will skip the file exist tests.

To change on a one-time basis the file names to be created or tested for:

--info-file foo.txt / --taglist-file foo.tag
  • --taglist-file, --tlf, --tf {file} — an alternate file name to use for --taglist. Note that file MUST have a *.tag extension, and should not be anything other than ASCII or UTF8, otherwise you will get ungood results. 🙈
  • --unique {comma separated tags} — the comma separated list of tag names will be used to set those tags to be used only 1x per file when found in auto.tag file, and unset after. You can also set this list manually in the auto.tag file top special field UNIQUE%:. This will make those tags work in a similar way to VERSION or PART or TITLE. TAGBLOCK value will treat each set of tags before the FILE%: item as applying only to that single file.

You need to add these tags in auto.tag right before the file tag block that will use that tag. Note that UNIQUE tags will override any global or tag block use of that tag name.

DO NOT USE IF TAG APPLIES TO MORE THAN ONE CONSECUTIVE FILE! In that case, set the tag before the block of files, and it will apply to all following files until the next new value. If it applies only to a block, and is not replaced by another value, use value UNSET for TAGNAME after the last file that uses it, unless that file is also the last file in the list. 💀

-La/-Lc UNSETs the tag at the end of each block of tags automatically.

-Lf/-Laf add value TAGBLOCK to UNIQUE automatically.

When used with -C, -M, or -S will set the UNIQUE value in the generated auto.tag file.

Sample: with command line:

acxi -s ./ -A --unique COMPOSER,ARRANGER

Sample: in auto.tag file: UNIQUE%:COMPOSERARRANGER 🦋

✨ ANALYZE/CHECKSUM OPTIONS ✨

Create checksum files (ffp/md5), verify checksums, analyze sets of files, check collection for duplicate ffps. This is the whole checksum-and-analysis corner of the group chat, bestie 💅

  • --analyze, -Z — Similar to -Xq, except it creates per file/directory reports with screen output. Shows input file quality (sample bit size, sampling rate, and channels), size, duration, kb/s, and also per directory summaries of those values. In the directory summary, if more than one input file quality type is found in a directory, it will print out each type found, which can be useful to see if different sampling rates or sample bit sizes were used.

To write to a file, use something like this:

acxi -s./ --analyze 2&>1 | tee analyze.txt

The tee will allow the output to also scroll on screen while it runs, which is helpful in many cases. Otherwise just redirect output to file directly.

  • -v 0 turns off per file reports, and shows only per directory summary.
  • -v 2 wraps per file data to key: value pair lines, adds ffp signature (flac only).
  • -v 3 adds raw non rounded seconds and file size in bytes to all size / time results.

Note that default for flac is metaflac, unless you use --ffprobe, which does not have hashes. Use metaflac for flac, it's about 25x or more faster than ffprobe!!

To verify -Xq, use -Xv instead, which will add an FFP verification report item to the analysis block.

  • --checksum, -K — Create .ffp and .md5 checksum files in your source directory. Checksum files are only created inside directories where flac files are found. Use --checksum-delete if you also want to delete existing checksum files before creating new ones. Only flac input type is supported.

This will not create md5 sums for files in directories that do not contain flac files, because that creates a very complicated logical puzzle which is hard to accurately or reliably resolve in code.

Do not use together with other cleaning/syncing options. Can be used with -A.

  • --checksum-delete, -D — Will first delete all .md5, .md5.txt, .ffp, .ffp.txt, .st5, and shntool.txt files before creating new checksum files. .st5 and shntool.txt were often created by shntool. Also removes robots.txt files, which sometimes were added by some downloaders in the past.

Note that some audio processing tools add .txt to the checksum file name, which creates undesirable outcomes since some tools that use .ffp or .md5 files don't recognize the files if they have the .txt extension added on.

I can think of very few reasons to want to preserve .ffp or .md5 files, since they should in general reflect what the actual files you have are.

Do not use together with other cleaning/syncing options. Can be used with -A.

  • --checksum-ffps, --ffps — Prints checksums to screen, disables md5 generation and output. Useful for generating large lists of ffps for a collection.

Similar to: acxi -K --no-md5 --test

Sample (prints to screen, redirects stderr to stdout, prints to file):

acxi -s ./ --ffps 2>&1 | tee ffps.txt
  • --checksum-verify, -V — Will read existing .md5 files and compare md5 hash of files listed in the md5 file with the actual checksums of those files. Also will verify FLAC integrity — this is pretty slow, so be patient 😭

Note that when reading md5s, it does not matter if they are windows or *nix path styles (/ or \), it translates them to the one on your system. It also ignores line endings, which makes reading windows generated md5 files on *nix systems a breeze.

See also -Xv for adding FFP verification item to that block.

  • --duplicates, --dupes — Check your collection for duplicated flac files or releases, helpful to find repeated items in your collection. Note that in cases of only 1 file matching, it's in theory possible for that to be a random coincidence, so always confirm before deleting anything!! But it's pretty rare for an ffp hash to be duplicated.

For larger directories/collections, use:

acxi -s./ --dupes 2>&1 | tee duplicates.txt

The tee will allow the output to also scroll on screen while it runs, which is helpful to see what's going on. Otherwise just redirect output to file directly.

  • --no-ffp — Skips FLAC ffp checks and generation on --checksum, --checksum-delete, and --checksum-verify. Useful if you have already verified or created ffp/flac data and only want to check md5 sums.
  • --no-md5 — Skips md5 checks and generation on --checksum, --checksum-delete, and --checksum-verify. Useful if you only want to check / create ffp data, which is much faster to generate than md5 checksums.
  • --z-min-size {number} — Override default value for --analyze min lossless file size alert. Number is integer KiB, 0-xxx. 0 disables this test. Can be set in config file, see config section.
  • --z-min-time {number} — Override default value for --analyze min file duration alert. Number is integer seconds, 0-xxx. 0 disables this test. Can be set in config file, see config section.

🎀 MISCELLANEOUS OPTIONS 🎀

Side quests, but make them useful 💖

  • --aggregate, -G [filename|extension] — Collect all the auto.tag files in a source directory and send to a target directory. Useful to collect data for a large collection. You can supply a list of comma separated items: jpg,info.txt,myart.png

Creates the directories the files were found in in the destination directory.

If no extra argument is supplied, it will default to collecting all the auto.tag files in the source directory.

  • Sample 1 (collects all auto.tag files): acxi --aggregate -s my-music -d music-data
  • Sample 2 (collects all supplied filename): acxi --aggregate info.txt -s my-music -d music-data
  • Sample 3 (collects all files of type jpg): acxi --aggregate jpg -s my-music -d music-data
  • Sample 4 (collects multiple values): acxi --aggregate jpg,info.txt,png -s my-music -d music-data
  • --config, --configuration — Show active configuration values, by file, and exit.
  • --help, -h — The help / options menu.
  • --no-ssl — Disable SSL strict certificate checks for -U.

Sample: cxi -U3 --no-ssl

This can be useful because codeberg.org doesn't usually allow connections without strict SSL checks, but legacy systems often have expired SSL certificates.

  • --update, -U [3] — Self updater, will update acxi and its man page. Non GNU/Linux will probably require changing the default values, which are set in USER VARIABLES for curl, acxi and man page acxi.1. Requires curl.

If you add 3 (-U 3), acxi will update from smxi.org server instead (that version is updated at least 1x per day, more during active development). Avoid this unless you have been asked to do it, or if you are running acxi on a legacy server with expired SSL certificates and need to use --no-ssl (-U 3 --no-ssl).

  • --version — Show acxi version.

🦋 DEBUG/OUTPUT CONTROL OPTIONS 🦋

These options allow you to modify the output, or to test actions before doing them for real. Very "look before you leap" of them, honestly 👑

  • --dbg {1-xx}[,1-xx] — Activate specialized debugger outputs. Accepts comma separated list of integers to trigger > 1 debugger action.

See stable branch docs/acxi-values.txt for more granular and current explanations.

  • 1 — Primary raw data.
  • 2 — Secondary raw data from text files.
  • 3 — Post processed secondary data.
  • 4 — File/Directory data during processing.
  • 5 — Command strings being run.
  • 6 — Generated data by subs, primary.
  • 7, 8 — Data from specific tools and utilities.
  • 20+ — Advanced data and debuggers.
  • --dry-run, --dry, --test — See --test.
  • --quiet, --silent — Turns off most screen output, except for error messages. Same as -v 0. Not used for all features since it makes no sense to turn off screen output for features that require screen output, like -Z.
  • --test, --dry, --dry-run — Test your configurations, copy, sync, checksum, and tagging actions without actually doing the operations.
  • --verbosity, -v {0-3} — Dynamically set verbosity. Helps for debugging certain types of issues where you might want advanced highly verbose debugging information.
    • 0 — shuts off most output except errors. Same as --quiet. Not useful or used for all features.
    • 1 — basic single line output.
    • 2 — more verbose output.
    • 3 — full output, including all conversion tool output.

For other technical data, see --dbg, but not unless you know why you are doing it.

🌸 CONFIGURATION FILE 🌸

You can see by running acxi -h the configuration file locations.

acxi will read its configuration/initialization files in the following order.

🌈 STANDARD DETECTION 🌈

/etc/acxi.conf contains the default configurations. Also checks /etc/acxi.conf.d/acxi.conf as global override for /etc/acxi.conf config file. Useful in cases if distros package acxi to override any defaults.

These can be overridden by user configurations found in one of the following locations, in this order of priority: $XDG_CONFIG_HOME/acxi.conf, $HOME/.config/acxi.conf, and, as last default, $HOME/.acxi.conf, i.e.:

$XDG_CONFIG_HOME/acxi.conf > $HOME/.config/acxi.conf > $HOME/.acxi.conf > /etc/acxi.conf.d/acxi.conf > /etc/acxi.conf

💜 MANUALLY SET 💜

$CONFIG_DIRECTORY — Sample:

$CONFIG_DIRECTORY='/path/to/configuration/directory'
NOTE: only use this method if you are running Windows, or any OS without $HOME or $XDG_CONFIG_HOME environmental variables, or if you want the configuration file to be located somewhere else.

This value must be set on top of acxi in the USER MODIFIABLE VALUES section because that is what it will use to locate the configuration file. acxi will look for acxi.conf inside that directory. This path value will override/ignore all other configuration files.

💅 CONFIGURATION OPTIONS 💅

okay bestie, these are the config-file versions of the USER MODIFIABLE VALUES section from the top comment header of acxi — same energy, just living in your config file instead of the script itself. slay.

Sample contents of a configuration file, fr fr:

DESTINATION_DIRECTORY=/home/fred/music/opus
SOURCE_DIRECTORY=/home/fred/music/flac
COPY_TYPES=gif,jpg,jpeg,png,txt
OUTPUT_TYPE=opus
QUALITY_OPUS=160
EXCLUDE=/doc/^^/docs/^^/images/^^/pictures/^^/artwork/^^/photos/^^

🛠️ APPLICATION PATHS 🛠️

these set your system path for the required applications, no cap:

  • COMMAND_FFMPEG — Sample: COMMAND_FFMPEG=/usr/bin/ffmpeg (default path)
  • COMMAND_FFPROBE — Sample: COMMAND_FFPROBE=/usr/bin/ffprobe (default path)
  • COMMAND_FLAC — Sample: COMMAND_FLAC=/usr/bin/flac (default path)
  • COMMAND_LAME — Sample: COMMAND_LAME=/usr/bin/lame (default path)
  • COMMAND_METAFLAC — Sample: COMMAND_METAFLAC=/usr/bin/metaflac
  • COMMAND_OGG — Sample: COMMAND_OGG=/usr/bin/oggenc (default path)
  • COMMAND_OPUS — Sample: COMMAND_OPUS=/usr/bin/opusenc (default path)

📁 SOURCE/DESTINATION/CONFIGURATION DIRECTORIES 📁

⚠️ NOTE: DESTINATION_DIRECTORY cannot be the same as SOURCE_DIRECTORY. periodt.
  • CLEAN — Sample: CLEAN=true. Switches on/off --clean sync to apply cleaning action to your destination directories. Accepted values: [enable|on|true|yes] or [disable|off|false|no]. Default is false.
  • DESTINATION_DIRECTORY — Sample: DESTINATION_DIRECTORY=/home/fred/music/ogg

This is the processed compressed music files, ie, ogg, opus, or mp3. Destination cannot be the same as Source directory, although it can be inside of the source directory.

  • SOURCE_DIRECTORY — Sample: SOURCE_DIRECTORY=/home/fred/music

This the original, working, like flac, wav, etc.

🚫 EXCLUDE LISTS/FILES 🚫

  • DOT — Disables default behavior of skipping all files starting with a .. Takes values true or false. Note that false is the acxi default so there's no point in using that.
  • EXCLUDE — Sample (if list): EXCLUDE=artwork^^Daisy Queen^^Bon Jovi

Sample (if exclude file): EXCLUDE=/home/me/music/excludes/acxi-excludes-phone.txt

Excludes these matches from destination directory in sync or clean operations.

  • EXCLUDE_BASE — Sample: EXCLUDE_BASE=massive-exclude-list

This is the part of the file name minus the .txt that will be matched to see if it's an exclude list or an exclude file. Default: acxi-excludes

This lets you use multiple exclude files, as long as they all contain the value found in EXCLUDE_BASE acxi will know it's an exclude file, not a list.

🎧 INPUT/OUTPUT 🎧

the following are NOT case sensitive, ie flac/FLAC, txt/TXT will be found. INPUT_TYPE and OUTPUT_TYPE will be forced to lower case internally.

changing quality levels will not redo existing files. (iykyk 😭)

  • CODEC_AAC — Sample (default value): CODEC_AAC=libfdk_aac
  • COPY_TYPES — Sample: COPY_TYPES=doc,docx,bmp,jpg,jpeg. Use this to override the default file types acxi will sync. Set to 'none', if you only want to sync the music files, not copy over images, text files, etc.
  • DITHER — Sample (default value): DITHER=shibata. See --dither for values.
  • INPUT_TYPE — Sample: INPUT_TYPE=flac
  • OUTPUT_TYPE — Sample: OUTPUT_TYPE=mp3
  • QUALITY_AAC — Sample: QUALITY_AAC=320. Supported values: 10 to 500. 500 is the largest file size / highest quality. Applies to aac and m4a.
  • QUALITY_FLAC — Sample: QUALITY_FLAC=5. Supported values: 0-8. 0 is the largest file size / fastest to run. 5 to 8 shows only a tiny decrease in file size but a large increase in time to process, so 4 is a good balance in general.
  • QUALITY_MP3 — Sample: QUALITY_MP3=2. Supported values: 0-9.999. 0 is the largest file size / highest quality. Decimals OK.
  • QUALITY_OGG — Sample: QUALITY_OGG=8.25. Supported values: -1 to 10. 10 is the largest file size / highest quality. Decimals OK.
  • QUALITY_OPUS — Sample: QUALITY_OPUS=256. Supported values: 6-256. 256 is the largest file size / highest quality / best bitrate.

🔍 ANALYZE 🔍

these two values let you customize default -Z ALERT warnings about possible incorrect file size and time duration values. super useful for finding accidentally corrupted or otherwise incorrect files, bestie 🫶

  • Z_MIN_SIZE — Sample: Z_MIN_SIZE=900. Minimum size (in KiB) in integers of lossless file. Not used for lossy files. Set to 0 to disable. See --z-min-size
  • Z_MIN_TIME — Sample: Z_MIN_TIME=8. Minimum time/duration in integer seconds of audio file. Set to 0 to disable. See --z-min-time

🏷️ AUTO-TAGGING 🏷️

these only apply to the --autotag option, and set a different name for the default auto.tag filename. the filename must be unique and never occur in any other context in your music collection files. no pressure or anything 💀

  • AUTOTAG_FILE — Sample: AUTOTAG_FILE=autotags.tag. Test with --autotag-file {file}.
  • auto.tag — The filename to be used to autotag. Default is auto.tag. Filename must be unique, and must not be found anywhere else in your collection. Do not change unless you have a very good reason to.
  • INFO_FILE — Sample (default value): INFO_FILE=info.txt
  • info.txt — The filename in the flac directory being processed that will be used to populate the auto.tag fields.
  • INFO_RATING — Sample (default value): INFO_RATING=4. See --info-rating. Used with -X q. Must be greater than 1.
  • PREFILL_TAG — Same syntax as --tag. Remember to clear this if you don't want these tags to be always used in prefill actions.

Sample: PREFILL_TAG=GENRE%:Heavy Metal^^IMAGE%:cover.jpg

  • TAGLIST_FILE — Sample: TAGLIST_FILE=taglists.tag
  • taglist.tag — The filename to be used by --taglist. Default is taglist.tag

Filename must be unique, and must not be found anywhere else in your collection. Do not change unless you have a very good reason to.

✅ CHECKSUMS ✅

these only apply to the --checksum option, and set a different name than the default file names used in the top section of acxi. note that the names should not include an extension, since that is added on automatically.

  • FFP_FILE — Sample: FPP_FILE=fingerprint. This is the name of the generated .ffp file, not including the .ffp extension, you want your flac ffp files to have.
  • MD5_FILE — Sample: MD5_FILE=checksum. This is the name of the generated .md5 file, not including the .md5 extension, you want your md5 checksum files to have.

🗣️ VERBOSITY LEVELS 🗣️

you can change VERBOSITY either at the top of the acxi file itself, or in the configuration file, by setting the verbosity/debugging level to what you want. Deprecated: LOG_LEVEL.

Sample: VERBOSITY=3

  • 0 — quiet/silent — no output at all (except for errors).
  • 1 — basic — single line per operation. This is the default, so you don't need to change it.
  • 2 — verbose — but without the actual conversion data from codecs
  • 3 — full — all available information. Note: with -F / --fork conversion output may be ordered somewhat randomly since it shows each thread's results as it completes as well as when it started.

🧠 ADVANCED 🧠

the following are advanced options which should only be used if you know what you are doing:

  • DONT_USE_NLINK — Sample: DONT_USE_NLINK=0. This sets File::Find::dont_use_nlink to 0 or 1. 1 is default. Generally you should be using 1, but in certain cases 0 may be faster. Test using the --nlink option to disable nlink, and see that option for more information.
  • FORK — Sample: FORK=4. This uses Perl's Parallel::ForkManager and accepts values of 0 or more. Note that 0 will not create a fork. See --fork for details. Using this will speed up your syncing a lot if you have more than a 1 core CPU.

🔄 SELF UPDATER 🔄

these are only for the -U self updater feature. the path defaults must be changed for non-GNU/Linux systems in most cases.

  • COMMAND_CURL — Sample: COMMAND_CURL=/usr/local/bin
  • MAN_DIRECTORY — Sample: MAN_DIRECTORY=/usr/share/man/man1. This is the directory the man page is in.
  • SELF_DIRECTORY — Sample: SELF_DIRECTORY=/usr/bin. This is the directory that acxi is in.

🐛 BUGS 🐛

please report bugs using the following resources. don't suffer in silence bestie 😭

Issue Report

File an issue report: https://codeberg.org/smxi/acxi/issues

Forums Post on acxi forums:

https://techpatterns.com/forums/about1491.html

IRC

You can also visit irc.oftc.net or irc.libera.chat channel: #smxi to post issues. Libera is probably best for acxi issues.

🏠 HOMEPAGE 🏠

https://codeberg.org/smxi/acxi

👑 AUTHOR AND CONTRIBUTORS TO CODE 👑

acxi is a fork and full rewrite of flac2ogg.pl.

Copyright (c) Harald Hope, 2010-2023

Initial forking logic: prupert. 2019-07

Initial MP3 tagging logic: Odd Eivind Ebbesen - www.oddware.net - <oddebb at gmail dot com>

Copyright (c) (flac2ogg.pl) 2004 - Jason L. Buberel - jason@buberel.org

Copyright (c) (flac2ogg.pl) 2007 - Evan Boggs - etboggs@indiana.edu

Thanks for trying acxi out, I hope it's useful to you.

and that's the whole page, bestie 🎀 this iconic little manual is for acxi 3.6.02, dated 2026-06-08 — go forth and sync slayfully 💖✨

📦 where this page comes from