This repository has been archived by the owner on Feb 17, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 3
acxi is an audio conversion tool that helps sync lossless to lossy formats.
License
smxi/acxi
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
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
About
acxi is an audio conversion tool that helps sync lossless to lossy formats.
Topics
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published