# `linuxwave` 🐧🎡

demo GitHub Release Coverage Continuous Integration Continuous Deployment Docker Builds Documentation

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

Table of Contents - [Motivation ✨](#motivation-) - [Installation πŸ€–](#installation-) - [Build from source](#build-from-source) - [Prerequisites](#prerequisites) - [Instructions](#instructions) - [Binary releases](#binary-releases) - [Arch Linux](#arch-linux) - [Void Linux](#void-linux) - [Docker](#docker) - [Images](#images) - [Usage](#usage) - [Building](#building) - [Examples 🎡](#examples-) - [Presets 🎹](#presets-) - [Usage πŸ“š](#usage-) - [`scale`](#scale) - [`note`](#note) - [`rate`](#rate) - [`channels`](#channels) - [`format`](#format) - [`volume`](#volume) - [`duration`](#duration) - [`input`](#input) - [`output`](#output) - [Funding πŸ’–](#funding-) - [Contributing 🌱](#contributing-) - [License βš–οΈ](#license-) - [Copyright ⛓️](#copyright-)
## Motivation ✨ - [Bash One Liner - Compose Music From Entropy in /dev/urandom](https://web.archive.org/web/20230122184930/https://blog.robertelder.org/bash-one-liner-compose-music/) - ['Music' from /dev/urandom](https://news.ycombinator.com/item?id=11238247) ## Installation πŸ€– ### Build from source #### Prerequisites - [Zig](https://ziglang.org/download/) (`0.10.1`) #### Instructions 1. Clone the repository. ```sh git clone https://github.com/orhun/linuxwave && cd linuxwave/ ``` 2. Update git submodules. ```sh git submodule update --init --recursive ``` 3. Build. ```sh 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](https://orhun.dev/linuxwave/docs). ### Binary releases See the available binaries for different targets from the [releases page](https://github.com/orhun/linuxwave/releases). They are automated via [Continuous Deployment](.github/workflows/cd.yml) workflow. Release tarballs are signed with the following PGP key: [0xC0701E98290D90B8](https://keyserver.ubuntu.com/pks/lookup?search=0xC0701E98290D90B8&op=vindex) ### Arch Linux `linuxwave` can be installed from the [community repository](https://archlinux.org/packages/community/x86_64/linuxwave/) using [pacman](https://wiki.archlinux.org/title/Pacman): ```sh pacman -S linuxwave ``` ### Void Linux `linuxwave` can be installed from official Void Linux package repository: ```sh xbps-install linuxwave ``` ### Docker #### Images Docker builds are [automated](./.github/workflows/docker.yml) and images are available in the following registries: - [Docker Hub](https://hub.docker.com/r/orhunp/linuxwave) - [GitHub Container Registry](https://github.com/orhun/linuxwave/pkgs/container/linuxwave) #### Usage The following command can be used to generate `output.wav` in the current working directory: ```sh docker run --rm -v "$(pwd)":/app "orhunp/linuxwave:${TAG:-latest}" ``` #### Building Custom Docker images can be built from the [Dockerfile](./Dockerfile): ```sh 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`: ```sh linuxwave ``` Or play it directly with [mpv](https://mpv.io/) without saving: ```sh linuxwave -o - | mpv - ``` To use the A minor blues scale: ```sh 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: ```sh linuxwave -i build.zig -n 261.63 -d 10 -o music.wav ``` Read from stdin via giving `-` as input: ```sh 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: ```sh 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: ```sh linuxwave -r 44100 -f U8 -c 2 -o chiptune.wav ``` Generate a **boss stage music** with the volume of 65: ```sh 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: ```sh 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](CONTRIBUTING.md) to show off your preset here! Also, see [this discussion](https://github.com/orhun/linuxwave/discussions/1) for browsing the music generated by our community. ## Usage πŸ“š ``` Options: -s, --scale Sets the musical scale [default: 0,2,3,5,7,8,10,12] -n, --note Sets the frequency of the note [default: 440 (A4)] -r, --rate Sets the sample rate [default: 24000] -c, --channels Sets the number of channels [default: 1] -f, --format Sets the sample format [default: S16_LE] -v, --volume Sets the volume (0-100) [default: 50] -d, --duration Sets the duration [default: 20] -i, --input Sets the input file [default: /dev/urandom] -o, --output 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](https://en.wikipedia.org/wiki/Semitone) 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](https://pages.mtu.edu/~suits/notefreqs.html). 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](https://github.com/orhun) useful, consider supporting me on [GitHub Sponsors](https://github.com/sponsors/orhun) or [becoming a patron](https://www.patreon.com/join/orhunp)! [![Support me on GitHub Sponsors](https://img.shields.io/github/sponsors/orhun?style=flat&logo=GitHub&labelColor=424242&color=1d1d1d&logoColor=white)](https://github.com/sponsors/orhun) [![Support me on Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dorhunp%26type%3Dpatrons&style=flat&logo=Patreon&labelColor=424242&color=1d1d1d&logoColor=white)](https://patreon.com/join/orhunp) [![Support me on Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dorhunp%26type%3Dpledges&style=flat&logo=Patreon&labelColor=424242&color=1d1d1d&logoColor=white&label=)](https://patreon.com/join/orhunp) ## Contributing 🌱 See our [Contribution Guide](./CONTRIBUTING.md) and please follow the [Code of Conduct](./CODE_OF_CONDUCT.md) in all your interactions with the project. ## License βš–οΈ Licensed under [The MIT License](./LICENSE). ## Copyright ⛓️ Copyright Β© 2023, [Orhun ParmaksΔ±z](mailto:orhunparmaksiz@gmail.com)