clamz(1)

📦 version 0.5, in debian bookworm, fedora 43, fedora 44, ubuntu jammy, ubuntu noble

💖 clamz(1) — the manual page, but make it cute 💖

okay so bestie, you're reading the manual page for clamz, section 1 of the General Commands Manual. she's little, she's mighty, she downloads your music. let's get into it 🎀

✨ NAME ✨

clamz — download MP3 music files from Amazon.com 🎵

🌸 SYNOPSIS 🌸

clamz [ options ] amz-file ...

🦋 DESCRIPTION 🦋

so clamz is this little command-line program that downloads MP3 files from Amazon.com's music store. she's basically standing in for Amazon's official MP3 Downloader, because that one is not free software — which means it only ships as a binary blob for a limited set of platforms. no source, no vibes. 🙈

with clamz you can download either individual songs or complete albums that you bought from Amazon. both. she does both. 👑

to even use clamz, you have to first enable the ``MP3 dowloader mode'' by visiting this URL:

http://www.amazon.com/gp/dmusic/after_download_manager_install.html?AMDVersion=1.0.9

if you're outside the US, swap amazon.com for whatever the domain is in your country (like amazon.co.uk for the UK, or amazon.fr for France). and heads up — Amazon does not allow anyone to purchase MP3 files from outside their country of residence. that's their rule, not mine. 😭

to download the contents of an AMZ file into the current directory, you literally just run:

clamz some-file-name.amz

and the more advanced options? they're all listed right below, bestie. keep scrolling. 💅

🎀 OPTIONS 🎀

  • -o name-format, --output=name-format — sets the name of the downloaded file(s). you can put any of several variables in there, and they get derived from the input AMZ file — peep FORMAT VARIABLES below for the full list. also, wrap that format string in single quotes so the shell doesn't go expanding your variables for you. she's nosy like that. 🙈
  • -d directory-format, --output-dir=directory-format — sets the directory where the downloaded files land. (if that directory doesn't exist yet, it gets created. iconic.) this one can hold format variables too. 📁
  • -r, --resume — resumes downloading a partially-downloaded album. here's the tea: by default, if you're downloading a file named foo.mp3 and foo.mp3 already exists in the destination directory, clamz renames the new file to foo.mp3.1 so it doesn't overwrite your old one. but with -r, she instead assumes the first part of the file has already been downloaded, and resumes from where it left off. ⏯️
  • -i, --info — instead of downloading anything, just prints detailed info about the given AMZ file(s) to standard output. all info, no download. 👀
  • -x, --xml — instead of downloading anything, prints the raw, decrypted XML data from the AMZ file to standard output. the raw tea, unedited. 📜
  • -v, --verbose — shows detailed information while downloading. she's telling you everything. 🗣️
  • -q, --quiet — turns off the normal progress display; only error messages get shown. shhh. 🤫
  • --forbid-chars=characters — don't allow the given characters in output filenames. important: control characters and slashes may never be used in filenames. never ever. 🚫
  • --allow-chars=characters — the opposite of the above; removes the given characters from the set of disallowed characters. un-forbidding, if you will. ✅
  • --allow-uppercase — allows uppercase letters in filenames. 🔠
  • --forbid-uppercase — does not allow uppercase letters in filenames. lowercase only, babe. 🔡
  • --utf8-filenames — uses UTF-8 when writing filenames. (the default behavior is to use UTF-8 if the system locale says so, otherwise ASCII.) 🌍
  • --ascii-filenames — uses only ASCII characters in filenames. 🌐
  • --help — prints out a summary of options. 🆘
  • --version — prints out version information. 🏷️

🌈 FORMAT VARIABLES 🌈

as part of a name-format or directory-format option, you can include references to environment variables (like $HOME) or to the xdg-user-dirs configuration variables (like $XDG_MUSIC_DIR or $XDG_DESKTOP_DIR). very much a "use your own setup" moment. 💖

on top of that, the following special variables are defined for each track, based on the info in the AMZ file, and subject to those configuration options above (--forbid-chars, --forbid-uppercase, etc.). so the options can change what you actually get. 🧚

  • ${title}, ${creator}, ${tracknum}, ${discnum}, ${genre}, ${asin} — the title, creator, track number, disc number, genre, and ASIN (Amazon Standard Identification Number) of each individual track. 🎧
  • ${album}, ${album_artist}, ${album_asin} — the title, primary artist, and ASIN of the album the track comes from. (this info is available both for single-track downloads and full-album downloads. equal opportunity.) 💿
  • ${suffix} — the suffix of the output file (currently only mp3.) 📎
  • ${amz_title}, ${amz_creator}, ${amz_genre}, ${amz_asin} — these variables formerly contained metadata for the AMZ file as a whole; current AMZ files do not contain this information. using these variables is not recommended. they're giving legacy. 💀

similar to shell variable expansion, you can also use these conditional expressions:

  • ${var:-string} — expands to the value of the variable var if it's defined and non-empty; otherwise, expands to string (which may itself contain variable references.) 🪄
  • ${var:+string} — expands to string if the variable var is defined and non-empty; otherwise, expands to an empty string. 🫧
⚠️ note that when you include format variables in a command-line argument, you'll usually need to enclose the argument in single quotes ('...'), or insert a backslash before the $, to stop the shell from trying to expand the variables itself. protect your variables, bestie. 🛡️

🍓 FILES 🍓

  • $HOME/.clamz/config — general configuration file, providing default settings for the --output, --forbid-chars, --allow-uppercase and --utf8-filenames options. the home base. 🏠
  • $HOME/.clamz/amzfiles/ — directory containing backup copies of AMZ files. 💾
  • $HOME/.clamz/logs/ — directory containing log files. 📓

⭐ ENVIRONMENT ⭐

  • http_proxy — HTTP proxy to use for downloading files; use server:port to specify a port number. 🔌

👑 AUTHOR 👑

Benjamin Moody <floppusmaximus@users.sf.net>

and that's the whole page, bestie!! you read the entire thing, main character energy fr fr. 🌟

this was Clamz 0.5, from October 2011, and yes she's still serving. mwah. 💅🫶

📦 where this page comes from