XWAX(1)

📦
version 1.10 · 5 versions
, in arch rolling, fedora 43, fedora 44, ubuntu stonking

🎀 XWAX(1) — Digital Vinyl on Linux 🎀

okay bestie, welcome to section 1 of the General Commands Manual 💖 this is the whole entire tea on xwax, and I'm gonna walk you through it like we're texting at 2am, except every single flag is still here. no skips. no "you get the idea". we're going all the way through, periodt.

✨ NAME ✨

xwax — Digital vinyl on Linux 🦋

✨ SYNOPSIS ✨

xwax [options] [-- path ...]

✨ DESCRIPTION ✨

so xwax is vinyl emulation software for Linux, and it's literally iconic for this. it lets DJs and turntablists playback digital audio files (MP3, Ogg Vorbis, FLAC, AAC and more 🌈) and you control all of it using a normal pair of turntables via timecoded vinyls. like, actual records spinning, actual needle, but the audio is your files. the way that works is lowkey genius. no cap.

✨ OPTIONS ✨

🚨 IMPORTANT VIBE CHECK: the ordering of options is important. most options apply to subsequent music libraries or decks, which can be given multiple times. see the EXAMPLES below, bestie. 👑
  • -l, --crate path — scan for tracks or a playlist at the given path. tracks get grouped into a crate in the music library. you can also just dump paths at the end of the command, after a -- argument. 🍓
  • --timecode name — use the named timecode for subsequent decks. run --help for a list of valid timecodes. you will need the corresponding timecode signal on vinyl to control playback — no vinyl signal, no control, that's the deal. 💅
  • --33 — set the reference playback speed for subsequent decks to 33 and one third revolutions per minute. this is the default, so it's giving main character energy without even trying.
  • --45 — set the reference playback speed for subsequent decks to 45 revolutions per minute. speed it up bestie 🌀
  • --[no-]protect — protect against loading new tracks or resetting the start of the track if the deck is playing. applies to subsequent decks, and the default is off. so yeah, by default it does NOT protect you. 🙈
  • --phono — adjust the noise thresholds of subsequent decks so they tolerate a cartridge-level signal plugged into a line-level audio interface. it's a 'software pre-amp'. but listen: unless your audio path has low noise, this will give worse results or may not work at all; a true phono pre-amplifier is always preferred. like, always. don't fight me on this one. 😭
  • --line — set noise thresholds of subsequent decks to standard audio levels. this reverses the effect of the --phono option, and is the default. we're back to normal, we're healed ✨
  • --import path — execute the given program to load tracks for playing. the program outputs a stream of signed, little-endian, 16-bit, 2 channel audio on standard output. yes that's very specific, write it down. 📝
  • --scan path — execute the given program to scan music libraries. applies to subsequent use of the --crate flag.
  • --dummy — create a deck which is not connected to any audio device, used for testing. a fake little deck, a simulation, a vibe 🫶
  • --lock-ram — lock into RAM any memory required for real-time use. this includes audio tracks held in memory which can be large. use ulimit -l to raise the kernel's memory limit to allow this. heads up: this can eat a LOT of memory. 💀
  • --rtprio n — change the real-time priority of the process. a priority of 0 gives the process no priority, and is used for testing only. only. for. testing.
  • --geometry [nxn][+n+n][/f] — change the geometry of the display in size, position and scale (zoom) respectively. the size and position is passed to SDL, which may use it to set the display mode, or size of an X window. see the EXAMPLES.
  • --no-decor — request to the window manager to create a 'frameless' window which does not have the regular controls such as title bars and buttons. this can be useful in conjunction with the --geometry flag for dedicated xwax appliances. dedicated appliance era 🧚
  • -h, --help — display the help message and default values. when in doubt, ask for help, bestie.

🔊 ALSA DEVICE OPTIONS 🔊

the following options are available only when xwax is compiled with ALSA support.

  • --alsa device — create a deck which uses the given ALSA device (eg. plughw:0).
  • --rate hz — set the sample rate for subsequent decks. the default is to prefer 48000Hz, but use 44100Hz if that is not available. to maintain best performance, only sample rates implemented by the hardware are available. so no making up numbers, the hardware has to actually do it. ⭐
  • --buffer samples — set the ALSA buffer size for subsequent decks. smaller is better for lower latencies and greater responsiveness. set too low and audible glitches will occur, with reports of underruns to the console. so like, don't go too small or it starts screaming at you. 😭

🎧 JACK DEVICE OPTIONS 🎧

the following options are available only when xwax is compiled with JACK support.

  • --jack name — create a deck which connects to JACK and registers under the given name.

xwax does not set the sample rate for JACK devices; it uses the sample rate given in the global JACK configuration. JACK decides, xwax respects it. mutual respect. 🤝

🌸 OSS DEVICE OPTIONS 🌸

the following options are available only when xwax is compiled with OSS support.

  • --oss pathname — create a deck which uses the given OSS device (eg. /dev/dsp).
  • --rate hz — set the sample rate for subsequent decks. the default for OSS devices is 48000Hz.
  • --oss-buffers n — set the number of buffers used by the OSS device. applies to subsequent decks.
  • --oss-fragment n — set the size of a buffer used by the OSS device. the actual buffer is 2^n bytes. applies to subsequent decks. yes, that's 2 to the power of n, math is math 🧮

🎛️ HARDWARE CONTROLLER OPTIONS 🎛️

the following options are available only when xwax is compiled with ALSA support.

  • --dicer device — use one or two Dicer controllers connected as the given ALSA device (eg. hw:Dicer). see the section NOVATION DICER CONTROLS for more information.

adding a hardware controller results in control over subsequent decks, up to the limit of the hardware. so the hardware decides how much it can handle, not you, sorry. 💅

⌨️ KEYBOARD CONTROLS ⌨️

the playback of each deck (direction, speed and position) is controlled via the incoming timecode signal from the turntables. the keyboard provides additional controls.

"C-" and "S-" means a keypress is combined with the 'Control' or 'Shift' key, respectively. iykyk ✨

record selection controls:

  • cursor up, cursor down — move highlighted record up/down by one.
  • page up, page down — scroll the record listing up/down by one page.
  • left cursor, right cursor — switch to the previous/next crate of records.
  • tab — toggle between the current crate and the 'All records' crate.
  • C-tab — toggle sort mode between: artist/track name, BPM and 'playlist' order. playlist order is the order in which records were returned from the scanner.
  • C-S-tab — re-scan the currently selected crate.

to filter the current list of records type a portion of a record name. separate multiple searches with a space, and use backspace to delete. it's giving search bar but make it DJ. 🔍

deck-specific controls:

deck 0 / deck 1 / deck 2, bestie — here's the whole mapping, nothing skipped:

  • F1 / F5 / F9 — load currently selected track to this deck.
  • F2 / F6 / F10 — reset start of track to the current position.
  • F3 / F7 / F11 — toggle timecode control on/off.
  • C-F3 / C-F7 / C-F11 — cycle between available timecodes.

the "available timecodes" are those which have been the subject of any --timecode flag on the command line. so whatever you declared on the command line is your little menu. 📋

audio display controls:

  • +, - — zoom in/out the close-up audio meters for all decks.

🎲 NOVATION DICER CONTROLS 🎲

the Novation Dicer provides hardware control of cue points. the controls are:

  • cue mode: dice button (1-5) — jump to the specified cue point, or set it if unset.
  • loop-roll mode: dicer button (1-5) — "punch" to the specified cue point, or set it if unset. returns playback to normal when the button is released.
  • mode button + dice button (1-5) — clear the specified cue point.

the dice buttons are lit to show that the corresponding cue point is set. cute little lights, love that for them. ✨

🌟 EXAMPLES 🌟

2-deck setup using one directory of music and OSS devices:

xwax --crate ~/music --oss /dev/dsp --oss /dev/dsp1

as above, but using ALSA devices:

xwax --crate ~/music --alsa hw:0 --alsa hw:1

2-deck setup using a different timecode on each deck:

xwax --crate ~/music --timecode serato_2a --alsa hw:0 --timecode
mixvibes_v2 --alsa hw:1

as above, but with the second deck at 45 RPM:

xwax --crate ~/music --timecode serato_2a --alsa hw:0 --timecode
mixvibes_v2 --45 --alsa hw:1

default to the same timecode, but allow switching at runtime:

xwax --crate ~/music --timecode serato_2a --timecode mixvibes_v2
--alsa hw:0 --alsa hw:1

3-deck setup with the third deck at a higher sample rate:

xwax --crate ~/music --rate 48000 --alsa hw:0 --alsa hw:1 --rate
96000 --alsa hw:2

using all three device types simultaneously, one deck on each:

xwax --crate ~/music --alsa hw:0 --oss /dev/dsp1 -j jack0

scan multiple music libraries:

xwax --crate ~/music --crate ~/sounds --crate ~/mixes --alsa hw:0

a shorter form of the above which can also be easier to script:

xwax --alsa hw:0 -- ~/music ~/sounds ~/mixes

load all subdirectories and put each one in its own crate, with support from the shell wildcard operator:

xwax --alsa hw:0 -- ~/music/*

scan a second music library using a custom script:

xwax --crate ~/music --scan ./custom-scan --crate ~/sounds --alsa
hw:0

control two decks with Dicer hardware:

xwax --dicer hw:Dicer --alsa hw:0 --alsa hw:1

use a high resolution and enlarge the user interface:

xwax --geometry 1920x1200/1.8 --alsa hw:0

🌈 HOMEPAGE 🌈

http://xwax.org/

👑 AUTHOR 👑

Mark Hills <mark@xwax.org>

and that's the whole page, bestie 🫶 this came from the xwax General Commands Manual, section 1 — the footer is just the little <rainbow>XWAX(1)</rainbow> tag doing its thing, and the header up top said the same, so now you know exactly where you are. go spin something iconic 💖🎀✨

📦 where this page comes from