linuxwave 🐧🎵

Click here to watch the demo!
Listen to "linuxwave" on Spotify!

Table of Contents

• Motivation ✨
• Installation 🤖
  • Build from source
    • Prerequisites
    • Instructions
  • Binary releases
  • Arch Linux
  • Void Linux
  • Docker
    • Images
    • Usage
    • Building
• Examples 🎵
• Presets 🎹
• Usage 📚
  • scale
  • note
  • rate
  • channels
  • format
  • volume
  • duration
  • input
  • output
• Funding 💖
• Contributing 🌱
• License ⚖️
• Copyright ⛓️

Motivation ✨

• Bash One Liner - Compose Music From Entropy in /dev/urandom
  • 'Music' from /dev/urandom

Installation 🤖

Build from source

Prerequisites

• Zig (0.10.1)

Instructions

1. Clone the repository.

git clone https://github.com/orhun/linuxwave && cd linuxwave/

2. Update git submodules.

git submodule update --init --recursive

3. Build.

zig build -Drelease-safe

Binary will be located at zig-out/bin/linuxwave. You can also run the binary directly via zig build run.

If you want to use linuxwave in your Zig project as a package, the API documentation is available here.

Binary releases

See the available binaries for different targets from the releases page. They are automated via Continuous Deployment workflow.

Release tarballs are signed with the following PGP key: 0xC0701E98290D90B8

Arch Linux

linuxwave can be installed from the community repository using pacman:

pacman -S linuxwave

Void Linux

linuxwave can be installed from official Void Linux package repository:

xbps-install linuxwave

Docker

Images

Docker builds are automated and images are available in the following registries:

• Docker Hub
• GitHub Container Registry

Usage

The following command can be used to generate output.wav in the current working directory:

docker run --rm -v "$(pwd)":/app "orhunp/linuxwave:${TAG:-latest}"

Building

Custom Docker images can be built from the Dockerfile:

docker build -t linuxwave .

Examples 🎵

Default: Read random data from /dev/urandom to generate a 20-second music composition in the A4 scale and save it to output.wav:

linuxwave

Or play it directly with mpv without saving:

linuxwave -o - | mpv -

To use the A minor blues scale:

linuxwave -s 0,3,5,6,7,10 -n 220 -o blues.wav

Read from an arbitrary file and turn it into a 10-second music composition in the C major scale:

linuxwave -i build.zig -n 261.63 -d 10 -o music.wav

Read from stdin via giving - as input:

cat README.md | linuxwave -i -

Write to stdout via giving - as output:

linuxwave -o - > output.wav

Presets 🎹

Generate a calming music with a sample rate of 2000 Hz and a 32-bit little-endian signed integer format:

linuxwave -r 2000 -f S32_LE -o calm.wav

Generate a chiptune music with a sample rate of 44100 Hz, stereo (2-channel) output and 8-bit unsigned integer format:

linuxwave -r 44100 -f U8 -c 2 -o chiptune.wav

Generate a boss stage music with the volume of 65:

linuxwave -s 0,7,1 -n 60 -v 65 -o boss.wav

Generate a spooky low-fidelity music with a sample rate of 1000 Hz, 4-channel output:

linuxwave -s 0,1,5,3 -n 100 -r 1000 -v 55 -c 4 -o spooky_manor.wav

Feel free to submit a pull request to show off your preset here!

Also, see this discussion for browsing the music generated by our community.

Usage 📚

Options:
  -s, --scale <SCALE>            Sets the musical scale [default: 0,2,3,5,7,8,10,12]
  -n, --note <HZ>                Sets the frequency of the note [default: 440 (A4)]
  -r, --rate <HZ>                Sets the sample rate [default: 24000]
  -c, --channels <NUM>           Sets the number of channels [default: 1]
  -f, --format <FORMAT>          Sets the sample format [default: S16_LE]
  -v, --volume <VOL>             Sets the volume (0-100) [default: 50]
  -d, --duration <SECS>          Sets the duration [default: 20]
  -i, --input <FILE>             Sets the input file [default: /dev/urandom]
  -o, --output <FILE>            Sets the output file [default: output.wav]
  -V, --version                  Display version information.
  -h, --help                     Display this help and exit.

scale

Sets the musical scale for the output. It takes a list of semitones separated by commas as its argument.

The default value is 0,2,3,5,7,8,10,12, which represents a major scale starting from C.

Here are other examples:

• A natural minor scale: 0,2,3,5,7,8,10
• A pentatonic scale starting from G: 7,9,10,12,14
• A blues scale starting from D: 2,3,4,6,7,10
• An octatonic scale starting from F#: 6,7,9,10,12,13,15,16
• Ryukyuan (Okinawa) Japanese scale: 4,5,7,11

note

The note option sets the frequency of the note played. It takes a frequency in Hz as its argument.

The default value is 440, which represents A4. You can see the frequencies of musical notes here.

Other examples would be:

• A3 (220 Hz)
• C4 (261.63 Hz)
• G4 (392 Hz)
• A4 (440 Hz) (default)
• E5 (659.26 Hz)

rate

Sets the sample rate for the output in Hertz (Hz).

The default value is 24000.

channels

Sets the number of audio channels in the output file. It takes an integer as its argument, representing the number of audio channels to generate. The default value is 1, indicating mono audio.

For stereo audio, set the value to 2. For multi-channel audio, specify the desired number of channels.

Note that the more audio channels you use, the larger the resulting file size will be.

format

Sets the sample format for the output file. It takes a string representation of the format as its argument.

The default value is S16_LE, which represents 16-bit little-endian signed integer.

Possible values are:

• U8: Unsigned 8-bit.
• S16_LE: Signed 16-bit little-endian.
• S24_LE: Signed 24-bit little-endian.
• S32_LE: Signed 32-bit little-endian.

volume

Sets the volume of the output file as a percentage from 0 to 100.

The default value is 50.

duration

Sets the duration of the output file in seconds. It takes a float as its argument.

The default value is 20 seconds.

input

Sets the input file for the music generation. It takes a filename as its argument.

The default value is /dev/urandom, which generates random data.

You can provide any type of file for this argument and it will generate music based on the contents of that file.

output

Sets the output file. It takes a filename as its argument.

The default value is output.wav.

Funding 💖

If you find linuxwave and/or other projects on my GitHub profile useful, consider supporting me on GitHub Sponsors or becoming a patron!

Contributing 🌱

See our Contribution Guide and please follow the Code of Conduct in all your interactions with the project.

License ⚖️

Licensed under The MIT License.

Copyright ⛓️

Copyright © 2023, Orhun Parmaksız