andyblight / acxi Goto Github PK

README for acxi - a comand line audio file conversion tool

See acxi.changelog for changes.

========================================================================
ABOUT
------------------------------------------------------------------------
acxi is a simple tool that syncs/converts lossless (flac, wav, raw) 
music libraries to compressed (ogg,mp3) versions of the lossless 
library. Its mission is to do one thing (sync to compressed formats
your music collection), and to do it well, in the classic Unix manner.

acxi doesn't change very often, and in general will 'just work' for 
as long as it's installed, though it is a good idea to check for 
updates now and then. It is used to process the lossless 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, like .txt, .jpg, .tiff, and 
so on, files, so you have a full copy of your originals in compressed 
format. It allows setting all variables, like compression rates, target 
and source directories, and and so on. You can add or remove these
file types using either top configuration, configuration file, or 
program option (-c).

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 -i /home/fred/media/main -o /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 (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.

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

Ogg encoding requires oggenc (Debian/Ubuntu package: vorbis-tools).
MP3 encoding requires: lame and flac (if source file is a flac, MP3
encoding does not support wav or raw formats).

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

========================================================================
CONFIGURATION
------------------------------------------------------------------------
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.

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.

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

acxi defaults to using ogg level 7/mp3 level 3 for output, and flac for 
input, and copies most common file types (which can be changed with -c 
or configuration values).

Once you set your input/output directory paths (using either -i / -o 
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.