README.txt

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 input/output directory paths (using either -s / -d options, or 
creating a configuration file), you can use the --test option to see what acxi 
would have done, then, once you have confirmed everything is working as 
expected, you can start syncing your music files.

In configuration file:

DESTINATTION_DIRECTORY=/home/you/music/opus 
SOURCE_DIRECTORY=/home/you/music/flac

If you want to exclude some directories from your lossy synced collection, use 
--exclude/-x or --exclude-append/-a, which will exclude those directory names 
from your lossy collection. This is useful to not transfer over stuff you won't 
use for lossy, like pdf files, image folders, documentation, artwork, and so on.

--exclude takes  ^^ separated list of key words which will match terms in your 
source directory you do not want synced or copied over to destination. Separate 
items with ^^. Will match the entire path so be aware. --exclude-append/-a adds 
types to your existing preset list. --exclude replaces that list.

For example: --exclude "/artwork^^/docs^^/pdfs"

To set these as permanent, use configuration item:

EXCLUDE=/artwork^^/docs^^/pdfs

--------------------------------------------------------------------------------
INPUT/OUTPUT & QUALITY

acxi defaults to flac for input, and defaults to the following quality levels 
for output:

* aac/m4a: 160

* flac: 4

* ogg: 7

* mp3: 3

* opus: 144

acxi also copies most common file types from source to destination directories. 

Output type can be set with -o/--output, input type with -i/--input, and quality 
level with -q/--quality options. The file types to copy over can be changed with 
-c/--copy, -a/--append, or configuration file values.

Input/Output types are set in configuration file like so:

INPUT_TYPE=flac
OUTPUT_TYPE=opus

Quality is set in configuration file per type:

QUALITY_FLAC=8
QUALITY_OPUS=160

See man page for full list and explanation of configuratin options.

--------------------------------------------------------------------------------
SCREEN OUTPUT VERBOSITY:

You can change the screen output verbosity using the following options:

* none (--quiet, -v 0)

* single line (-v 1)

* verbose (-v 2)

* full, with all conversion tool outputs (-v 3)

Screen verbosity output values can be set in configuration file using:

VERBOSITY=[0-3]

================================================================================
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 native aac codec, or libfdk_aac 
(best, Debian/Ubuntu package libfdk-aac2). If you want to preserve tags, use 
m4a, if you use aac they will not transfer.

* FLAC -> FLAC requires ffmpeg. 

* FLAC resampling requires ffmpeg and metaflac (for source file sample data).

* MP3 encoding requires: lame and flac (if source file is a flac, MP3 encoding 
does not support wav or raw 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, -X [qv], and --ffps require metaflac.

* --analyze, --infofix q if input type not flac, or flac + --ffprobe, require 
ffprobe.

* --autotag requires metaflac plus a specially formatted auto.tag file placed 
inside each album/collection directory.

* --checksum/--checksum-delete checksum generation require metaflac and md5sum 
(or a comparable md5 generating command line utility).
  
* --checksum-verify requires md5sum (or comparable tool) and flac.

* --fork requires Perl module Parallel::ForkManager

* --image, --remove-images, and --taglist require metaflac.

* --infofix c requires Perl Core Module Encoding::Guess

* --infofix k requires Perl Core Module POSIX::strftime

* --infofix t and u require Perl module Text::Autoformat

* --infofix v requires flac.

* -U self updater requires curl, and valid paths for currently installed acxi 
and acxi.1 man page. Will not update if both acxi and acxi.1 are not present on 
your system, and correct paths set.

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'.

================================================================================
SPECIAL NOTES ABOUT CODECS
--------------------------------------------------------------------------------

There's a few things that need to be done to use some of the codecs.

--------------------------------------------------------------------------------
AAC:

You can usually install the Frauenhofer libfdk_aac codec if you use the proper 
non-free repositories. In Debian/Ubuntu, the package is libfdk_aac2. Otherwise 
you can use the ffmpeg native aac codec, but it has been tested and found less 
good than the fdk_aac codec. Your call. 

Read more about the technical comparisons here:
https://trac.ffmpeg.org/wiki/Encode/AAC

FFMPEG does not transfer tags when the file format is aac, but it does when it's 
m4a, so if you have tagged flac source files, then use m4a instead of aac and 
most of your tags will transfer fine automatically. 

Personally I have no interest in mapping tags to propietary non free formats in
AAC, so if anyone wants to create a function to do that, feel free. See the mp3
tag mapper feature for ideas. But really, just use m4a and call it a good.

--------------------------------------------------------------------------------
SHN SHORTEN:

Finding the shorten codec can be a pain, here's a few sources that may help. You 
probably already have the codec if you have shn files and have been playing 
them.

http://wiki.etree.org/index.php?page=SoftwareYouNeed
See section: Uncompress 
http://adventuresinswitching.blogspot.com/2008/04/convert-shn-shorten-to-mp3-or-flac-in.html
has a good selection of methods for Linux, including compiling directions.

Check for a package/port called 'shorten' in *nix systems, and for Windows, 
you'll want to find the shorten.exe. 

Arch, Ubuntu, etc, have the shorten package available. deb-multimedia.org has 
the shorten codec package for Debian.

For a collection of plugins and other shorten items:
http://shnutils.freeshell.org/shorten/

http://shnutils.freeshell.org/shorten/dist/src/ has the shorten 
tar.gz files if you want to compile the codec yourself.

$ ./configure
$ make
$ make check
$ sudo make install