audiowaveform(1)

📦 version 1.10.3, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

okay so bestie, welcome to audiowaveform — the little icon that generates and renders waveforms from audio files. literally does what it says on the tin, no cap. ✨

quick housekeeping: this whole page lives in the General Commands Manual section, and i'm gonna walk you through it like we're texting at 2am. 🫶

🌈 SYNOPSIS 🌈

audiowaveform [options]

that's it. that's the whole vibe. the options do all the heavy lifting, iykyk. 💅

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ — audiowaveform generates waveform data from audio files in MP3, WAV, FLAC, Ogg Vorbis, or Opus format. and what is waveform data for? it's for producing a visual rendering of the audio — the same kind of look you'd see in an audio editing app. literally so satisfying to look at. 👑

waveform data files get saved in either binary format (.dat) or JSON (.json). and here's the cute part — if you hand it an input waveform data file, audiowaveform can also render the audio waveform as a PNG image at a given time offset and zoom level. main character energy. 🎀

so how does the waveform data actually come out of the audio signal? bestie, i'm so glad you asked:

  1. first it combines the input channels to produce a mono signal
  2. then it computes the minimum and maximum sample values over groups of N input samples — where N is controlled by either the --zoom or the --pixels-per-second option — such that each N input samples produces one pair of minimum and maximum points in the output

every N samples = one min/max pair. slay. 🌸

and if you want the nitty gritty on the binary and JSON waveform data file formats? go read audiowaveform(5). it's giving lore. 📖

✨ OPTIONS ✨

okay bestie, buckle up, this is the long one but every single flag matters. 💜

  • --help — shows the help message. the "hello, what do you do" flag. 🙈
  • --version, -v — shows version information. the "who are you and when were you born" flag. 🎀
  • --quiet, -q — disables status messages. for when you want silence and peace. 🤫
  • --input-filename, -i <filename> — the input filename! it should be a MP3, WAV, FLAC, Ogg Vorbis, or Opus audio file, or a binary or JSON format waveform data file. by default, audiowaveform uses the file extension to decide how to read it — so either .mp3, .wav, .flac, .ogg, .oga, .opus, .dat, or .json as appropriate — but bestie, you can override all that with the --input-format option. and if --input-filename is - or is omitted, audiowaveform reads from standard input, and then the --input-format option must be used to specify the data format. no guesswork allowed. 😤
heads up babes: Opus support requires libsndfile 1.0.29 or later, so it may not be available on all systems. fr fr check your version before you come for me. 💀
  • --output-filename, -o <filename> — the output filename! which may be either a WAV audio file, a binary or JSON format waveform data file, or a PNG image file. by default, audiowaveform uses the extension to decide what kind of output to generate — .wav, .dat, .json, or .png as appropriate — but again, override with --output-format if you're feeling spicy. and if --output-filename is - or is omitted, audiowaveform writes to standard output, and the --output-format option must be used to specify the data format. 👑
  • --input-format <format> — the input data format, either wav, mp3, flac, ogg, opus, dat, or json. this option must be used when reading from standard input. it may also be used to set the input file format instead of letting it be determined from the file extension from the --input-filename option. ✨
  • --output-format <format> — the output data format, either wav, dat, json, or png. this option must be used when writing to standard output. it may also be used to set the output file format instead of letting it be determined from the file extension from the --output-filename option. 🌸
  • --zoom, -z <zoom> (default: 256) — when creating a waveform data file or image, specifies the number of input samples to use to generate each output waveform data point. 📏 note: this option cannot be used if either the --pixels-per-second or --end option is specified. and when you're creating a PNG image file, a value of auto scales the waveform automatically to fit the image width. iconic behavior honestly. 🧚
  • --pixels-per-second <zoom> (default: 100) — when creating a waveform data file or image, specifies the number of output waveform data points to generate for each second of audio input. 📐 note: this option cannot be used if either the --zoom or --end option is specified. pick a lane bestie. 💅
  • --bits, -b <bits> (default: 16) — when creating a waveform data file, specifies the number of data bits to use for output waveform data points. valid values are either 8 or 16. that's it, that's the list. 🎯
  • --split-channels — output files are multi-channel, not combined into a single waveform. the way that it just keeps every channel separate?? obsessed. 🦋
  • --start, -s <start> (default: 0) — when creating a waveform image, specifies the start time, in seconds. ⏱️
  • --end, -e <end> (default: 0) — when creating a waveform image, specifies the end time, in seconds. ⏲️ note: this option cannot be used if the --zoom option is specified. sorry babe, them's the rules. 😭
  • --width, -w <width> (default: 800) — when creating a waveform image, specifies the image width. 📐
  • --height, -h <height> (default: 250) — when creating a waveform image, specifies the image height. 📏 (yes, -h is height here, not help — stay woke 👀)
  • --colors, -c <colors> (default: audacity) — when creating a waveform image, specifies the color scheme to use. valid values are either:
    • audacity — generates a blue waveform on a grey background, similar to Audacity
    • audition — generates a green waveform on a dark background, similar to Adobe Audition

aesthetic choices, both valid. 🎨

  • --border-color <rrggbb[aa]> — when creating a waveform image, specifies the border color. if not given, the default color used is controlled by the --colors option. the color value should include two hexadecimal digits for each of red, green, and blue (00 to FF), and optional alpha transparency (00 to FF). so like, hex codes bestie. 💅
  • --background-color <rrggbb[aa]> — when creating a waveform image, specifies the background color. if not given, the default color used is controlled by the --colors option. 🖼️
  • --waveform-color <rrggbb[aa]>[, <rrggbb[aa]>, ...] — when creating a waveform image, specifies the waveform color. if not given, the default color used is controlled by the --colors option. and plot twist: this option accepts multiple comma-separated color values, which are used with the --split-channels option to produce a waveform image with multiple channels. so you can make it all rainbow. 🌈
  • --axis-label-color <rrggbb[aa]> — when creating a waveform image, specifies the axis labels color. if not given, the default color used is controlled by the --colors option. 🌸
  • --with-axis-labels, --no-axis-labels (default: with axis labels) — when creating a waveform image, specifies whether to render axis labels and image border. on or off, your call. ✨
  • --amplitude-scale <scale> (default: 1) — when creating a waveform image or waveform data file, specifies an amplitude scaling (or vertical zoom) to apply to the waveform. must be either a number or auto, which scales the waveform to the maximum height. 📈
  • --waveform-style <style> (default: normal) — when creating a waveform image, specifies how the waveform is drawn. valid values are either:
    • normal — draws a normal waveform
    • bars — draws the waveform as vertical bars

bars mode is so cute, highly recommend. 🔥

  • --bar-width <width> (default: 8) — when creating a waveform image with the --waveform-style bars option, specifies the width of each bar, in pixels. 🍓
  • --bar-gap <width> (default: 4) — when creating a waveform image with the --waveform-style bars option, specifies the separation between each bar, in pixels. 🌸
  • --bar-style <style> (default: square) — when creating a waveform image with the --waveform-style bars option, specifies how each bar is drawn. valid values are either:
    • square — draws the waveform bars with square corners
    • rounded — draws the waveform with rounded corners

rounded is giving cozy. 🎀

  • --compression <level> (default: -1) — when creating a waveform image, specifies the PNG compression level. must be either -1 (default compression) or between 0 (fastest) and 9 (best compression). trade-offs, bestie. ⚖️
  • --raw-samplerate <rate> — when using raw input audio format, this must be set to the appropriate sample rate, in Hz. ⏰
  • --raw-channels <n> — when using raw input audio format, this must be set to the appropriate number of channels. 🎚️
  • --raw-format <format> — when using raw input audio format, this must be set to the appropriate sample format. valid options are s8, u8, s16le, s16be, s24le, s24be, s32le, s32be, f32le, f32be, f64le and f64be. yes, all twelve of them, count 'em. 👑 (also the original had a lil double space before s8, but we fixed the vibes not the facts 😌)

🎀 EXAMPLES 🎀

this is the part where it gets fun. copy-paste away bestie. 💖

generate waveform data from an MP3 file, at 256 samples per point with 8-bit resolution:

audiowaveform -i test.mp3 -o test.dat -z 256 -b 8

generate waveform data containing multiple channels, rather than combining all channels into a single waveform:

audiowaveform -i test.mp3 -o test.dat -z 256 -b 8 --split-channels

generate waveform data in JSON format from a FLAC file, at 256 samples per point with 8-bit resolution:

audiowaveform -i test.flac -o test.json -z 256 -b 8

generate a 1000x200 pixel PNG image from a waveform data file, at 512 samples per pixel, starting at 5.0 seconds from the start of the audio:

audiowaveform -i test.dat -o test.png -z 512 -s 5.0 -w 1000 -h 200

generate a 1000x200 pixel PNG image from a waveform data file, starting at 5.0 seconds from the start of the audio, ending at 10.0 seconds:

audiowaveform -i test.dat -o test.png -s 5.0 -e 10.0 -w 1000 -h 200

generate a 1000x200 pixel PNG image from a waveform data file, at 200 pixels per second, starting at 5.0 seconds from the start of the audio:

audiowaveform -i test.dat -o test.png --pixels-per-second 200 -s 5.0 -w 1000 -h 200

generate a 1000x200 PNG image directly from a WAV file, at 300 samples per pixel, starting at 60.0 seconds from the start of the audio:

audiowaveform -i test.wav -o test.png -z 300 -s 60.0 -w 1000 -h 200

generate a 1000x200 PNG image from an MP3 file, showing the entire duration:

audiowaveform -i test.mp3 -o test.png -w 1000 -h 200 -z auto

generate a 1000x200 PNG image from an MP3 file, using a custom bar style:

audiowaveform -i test.mp3 -o test.png -w 1000 -h 200 -z auto --waveform-style bars --bar-width 10 --bar-gap 2

generate a waveform data file from standard input, to standard output, using ffmpeg to convert a video file to WAV format:

ffmpeg -i test.mp4 -f wav - | audiowaveform --input-format wav --output-format dat -b 8 > test.dat
💡 Note: if you want to render multiple images from the same audio file, it's generally preferable to first create a waveform data (.dat) file, and create the images from that — because decoding long MP3 files can take significant time. bestie please don't make your laptop suffer. 😭

convert a waveform data file to JSON format:

audiowaveform -i test.dat -o test.json

convert MP3 to WAV format audio:

audiowaveform -i test.mp3 -o test.wav

💀 LIMITATIONS 💀

the audiowaveform program has the following limitations, and yes we're saying them out loud:

  • when generating PNG images, the maximum audio sample rate is 50,000 Hz. ⚠️
  • when generating PNG files, it is not valid to specify a zoom level smaller than that used to generate the input waveform data file. 🚫

🔥 SEE ALSO 🔥

audiowaveform(5) — go read it, it's the whole format lore. 📚

🫶 AUTHOR 🫶

Chris Needham — thank you for this icon, we stan. 👑

and that's the whole page bestie!! 🎀✨ this lil rewrite is from audiowaveform(1) in the General Commands Manual, dated 23 January 2024 — so if anything's changed since then, blame the calendar not me. 💖 mwah, go make some pretty waveforms. 🦋

📦 where this page comes from