Acxi

README for acxi - a command line audio processing tool.

================================================================================ CODEBERG REPOS

Please file issue reports or feature requests at:

https://codeberg.org/smxi/acxi

The Codeberg repos will be mirrored to Github until the end of 2023, after that, no updates to github repos will be made. Some time after that, the code will be removed.

Please take the time to read this helpful article from the Software Freedom Conservancy:

https://sfconservancy.org/GiveUpGitHub/

Any use of this project's code by GitHub Copilot, past or present, is done without my permission. I do not consent to GitHub's use of this project's code in Copilot.

================================================================================ DOCUMENTATION RESOURCES

acxi.changelog: https://codeberg.org/smxi/acxi/raw/stable/acxi.changelog For complete, up to date, current state of acxi development, features, and fixes.

HTML changelog: https://smxi.org/docs/acxi-changelog.htm If you find the HTML version of the changelog easier to read.

HTML man page: https://smxi.org/docs/acxi-man.htm This is highly recommended for new users since it fairly complete and explains most things reasonably completely, and has examples, etc.

HTML help menu: https://smxi.org/docs/acxi-options.htm Useful to get a quick overview of acxi options.

Debugging switches for --dbg, and other developer required data: stable branch: docs/acxi-values.txt

================================================================================ INSTALLATION

Easy way to install. Change paths on local system if required.

With acxi 3.2.16 or newer, self updater: sudo acxi -U

Or, to install the man and acxi files manually:

These are for GNU/Linux. These use a redirecting shortcut from smxi.org sudo wget -O /usr/local/bin/acxi smxi.org/acxi

Then make executable: sudo chmod +x /usr/local/bin/acxi

For man page: sudo wget -O /usr/local/share/man/man1/acxi.1 smxi.org/acxi.1

If you prefer to use the full Codeberg paths:

Program: sudo wget -O /usr/local/bin/acxi https://codeberg.org/smxi/acxi/raw/stable/acxi

Man page: sudo wget -O /usr/local/share/man/man1/acxi.1
https://codeberg.org/smxi/acxi/raw/stable/acxi.1

If you want to use the -U self-updater option, both acxi and the man page must be present on your system, and paths to them set either by placing them in the default locations above, or adding the required configuration paths.

================================================================================ MAIN FEATURES

acxi is a tool that syncs/converts lossless (flac, wav, raw) music libraries to compressed (mp3,ogg,opus) versions of the lossless library. It also can convert aif, raw, shn, and wav to flac. It also creates/checks md5, ffp files, tags your collection, embeds images, gets tags from your collection, and much more. Read the man page for specifics on how to use the features. Some are quite powerful but have a significant learning curve to use effectively.

acxi is developed as features are requested or discovered useful. It will in general 'just work' for as long as it's installed, though it is a good idea to check for updates now and then since bugs get fixed, new features are added or extended. Changes will not break existing configurations.

Most options where it makes sense have corresponding configuration items.

---

TEST ACTIONS:

Using --dry-run/--dry/--test option allows you to see what acxi would have done for syncing, tagging, and checksum creation actions, without actually running those.

---

SYNCING:

In its syncing role, acxi is used to process lossless collections of files generated by programs like abcde, the audio cd ripping tool, and makes for very easy updating/syncing of all your music collections.

It also copies over all associated data to the lossy synced collection, like .txt, .jpg, .png files. You can add or remove these file types using either top configurations, configuration file, -a [one or more comma separated extensions] to add/apppend a file type temporarily, or -c [comma separated extension list] to supply a new list. This results in you having a full copy of your originals in compressed format.

You can set exclude filenames/directories so you don't add those undesired files or folders to your synced collection. It further supports, via --clean, the option to remove clutter from your lossy collection.

You can set all core variables, like compression rates, target and source directories, and and so on.

For instance, say you have: /home/fred/media/main which contains your flac music directories, and you want to sync up your ogg versions in: /home/fred/media/ogg You would run: acxi -s /home/fred/media/main -d /home/fred/media/ogg and acxi would mirror the directory structure, copy over all the jpg, png, txt, etc, type files, and then encode your flacs to ogg.

If your ogg, opus, or mp3, directory is located at: /home/fred/media/main/ogg that is, in your 'main' directory, acxi will handle that, and ignore that directory when syncing.

If you run acxi routinely, it will just copy/sync over changed or new files. Note that acxi will not change to a different compression level already compressed versions, so if you want to change your compression levels, you have to use the -f/--force option.

---

TAGGING:

Using acxi's native auto.tag file format, you can readily tag your recordings. You can update info text files (--infofix/-X), use that info file as source for auto.tag file creation (-ES/-EM), or just create the auto.tag file without any prefills except track file names and disk totals etc. The generated auto.tag file can then be used to tag your recordings (--autotag/-A).

-X supports several types of info file fixes (see help/man for various fix options), and also allows you to see what would happen without writing it to file, then by adding 'w' to the -X command (like -Xdtw), writes changes to info file.

You can also manually add tags using the --tag/-T option, or embed / remove images with the --image/-I and --remove-images/-R options.

-L/--taglist shows you what tags exist in one or more directories of FLACs. That works in a similar way to -X, offering a variety of actions, to either create an info.txt file from the existing tags, or to output the tags in either full per file format (default, -L f), or a condensed format, which puts all common tag data on top of the file, and only different data per file/block of files.

With -La, you end up with an auto.tag file, which can then be used, or modified/edited, then used, to tag your files using -A. As with -X, adding w writes out the file(s).

Read the man page for more on auto tagging and info file/tag processing.

---

CHECKSUMS AND TESTS:

acxi can generate new checksum files (--checksum/-K) (md5 and ffp), and verify existing md5 hashes and flac file integrity (--checksum-verify/-V and --infofix v/-Xv).

The --duplicates/--dupes option allows bulk checks of a collection for duplicate flac files.

The --checksum-ffps/--ffps option allows you to generate on screen full listing of all recordings in a directory, with file lists, ffp checksums, and track counts per directory.

The --analyze/-Z option creates a per directory report of given input type file sizes, times, kbps, then a summary report per directory of hte total size, time, average kbps. This report, as with --dupes, prints to screen, and can be redirected to a file.

---

ERROR CORRECTION AND VALIDATION:

In order to avoid as many possible user error situations as possible, acxi tries to verify and validate all requested operations, and exit if an impossible situation is requested, or if incorrect or not valid data was supplied.

================================================================================ CONFIGURATION AND USE

acxi supports configuration files at either /etc/acxi.conf, or user override files $XDG_CONFIG_HOME/acxi.conf, $HOME/.acxi.conf, or $HOME/.config/acxi.conf. The user configuration values override any /etc/acxi.conf values.

Sample acxi.conf file included here if you want to use that in a package or as your configuration file.

See the man page for complete explanations.

If your system does not have the $HOME or $XDG_CONFIG_HOME environmental variables (Windows, for example), you can use the manual config file path option

$CONFIGURATION_DIRECTORY='';

to create a path to your acxi.conf configuration file.

See the top of acxi, or the man page, for instructions on how to create the configuration items. Note that user values in configuration files do not use the '$' you see in the top user configuration section, for example, $SOURCE_DIRECTORY would be used as: SOURCE_DIRECTORY=path in your configuration file.

---

SOURCE/DESTINATION DIRECTORIES:

You must at a minimum set your source and destination directories the first time you run acxi, either using the -s/--source and -d/--destination options, or in the USER VARIABLES section on the top of the file, or in a configuration file.

Once you set your