Command line

euphoria analyze

Shows the key, tempo, energy and sound quality of audio files.

euphoria analyze [OPTIONS] <PATHS>...

Each path is a file or a folder. Folders are searched recursively for supported audio files. Hidden files and folders are skipped, including the ._ copies macOS leaves on external drives. A file named directly is always analyzed, so an unsupported file is reported as a failure instead of being ignored.

A symbolic link to an audio file is analyzed. A symbolic link to a folder is not entered, so a scan stays inside the folders you named; to include a linked folder, name it on the command line.

Each run searches the folders again, so files added since the last run are analyzed and files deleted since then are simply no longer listed. Nothing records what an earlier run found, so a deleted file is not reported as removed; the desktop app’s rescan is the one that counts removed tracks. A file analyzed before, even under another name or in another folder, comes back from the cache without analyzing it again.

How the results are shown depends on where they go:

Output Shown as
A terminal, several files A table that fits the window, then a summary.
A terminal, one file, or any output with --detail A detailed view of each track.
A pipe or a file The plain table, with the same columns every time, for scripts.
Any output with --json JSON.

A - means nothing was detected, for example in silence or a track shorter than one second.

Beat grid from rekordbox

--collection <FILE> takes your rekordbox collection exported as XML (File > Export Collection in xml format). A track listed there, matched by its file location, with a constant beat grid uses that grid in place of the detected one: beat_grid and bpm are the grid’s, and the cues are placed again on its bars. The detailed view and the JSON say where each grid came from, rekordbox, detected or you; see use your rekordbox beat grid for the rules. JSON adds beat_grid_source and, with --collection, rekordbox_grid: used, variable, unsupported meter, unreadable, no grid or not in collection. The confidence of an imported grid is null. Standard error says how many tracks use the collection’s grid and lists those whose grid could not be used, with the reason.

The table on a terminal

$ euphoria analyze ~/Music/DJ
Key           Tags        BPM  Energy              Quality   Time  Review    File
 8A  A minor  =         124.0       6  ━━━━━━────  lossless  6:48            Low Tide.flac
10B  D major  9A other  149.8       6  ━━━━━━────  weak      2:00  key+tags  edits/Intro.m4a

Key and tempo: 1 of 2 tracks worth checking by ear, where the key may be its relative or a fifth away, or the BPM half or double.
Tag keys: 1 of 2 tracks with a key in their tags differ from the detected key (1 different key).
Sound quality: 1 track lossless, 1 weak on a big system.
hint: --needs-review lists only the tracks to check by ear, with those whose tags name another key.
hint: --detail says which reading to trust.
hint: euphoria quality lists the files worth replacing, worst first, with why.

The key is shown in the notation --key-notation picks, coloured by its number on the Camelot wheel as in the app, with the key in another notation beside it. The table shows no confidence ratings; the Review column below says which tracks are worth checking by ear, and --needs-review lists only those. The ratings are still in the JSON output, and accuracy explains how they are set.

The Review column says why a track is worth checking, in a word for each reason: key (the key may be its relative or a fifth away), tempo (the BPM may be half or double: half or double it is a tempo a DJ could count, the same bpm_alternative as in --json, and the tempo is rated low or the onsets back that octave more strongly), tags (the tags name another key) and failed. It is the list the desktop app shows as Needs review, computed by the same code. A track whose doubtful values you confirmed with Looks right in the app shows checked and is no longer listed by --needs-review; a key or tempo you set is not in doubt either. The column is left out when no track has a reason or a confirmation, and in a narrow window it is left out right after the Tags column. The plain table has no Review column; use --json.

The Tags column compares the key already written in each file’s tags with the detected key. Euphoria reads the key field of every format it writes: TKEY in MP3, AIFF and WAV files, initialkey or KEY in M4A files, and INITIALKEY or KEY in FLAC and Ogg files, in Camelot (8A, 08A), Open Key (1m) or musical notation (Am, A min, A minor, Abm), so a key written by Euphoria, rekordbox, Mixed In Key or Traktor is read alike. A tempo after the key, as in 8A 114, and an energy label, as in 8A - Energy 7, are ignored. = means the tags name the detected key, ? that the field holds text that is not a key, and otherwise the column shows the key from the tags and how it differs: fifth (one step on the Camelot wheel), relative (the same number, the other letter), parallel (the same home note, the other mode) or other. A track whose tags name another key is listed by --needs-review, unless you set or confirmed its key yourself. The column is left out when no file has a key in its tags. Analyzing only reads the tags: it never changes them.

The detailed view also shows the track’s set stage on a Stage line, when it has one. Energy is the energy rating from 1 to 10, with a bar of ten cells. It is Euphoria’s own scale, so do not compare it with the energy numbers of other tools.

Quality is the audio quality verdict for DJ use in a word: lossless, limited bw (a lossless file whose content stops below 19 kHz with a gradual roll-off: information, not a defect), good, acceptable, weak (weak on a big system) or re-encoded? (likely made from a lower quality file). The detailed view gives the reason.

The folder that holds every file is left out of the File column, so a folder shows its file names and the subfolders below it. A name too long for the window is shortened in the middle, keeping its end and extension.

In a narrow window, the least needed columns are left out first: the energy bar, the key in the other notation, the time, the Tags column, the Review column, the quality, then the energy. The key, the tempo and the file always stay.

After the table, standard error gets a summary in plain sentences: how many tracks have a doubtful key or BPM not yet confirmed by you, how many have a key in their tags that differs from the detected one and in which way, how many have each sound quality, how many files could not be analyzed, and hint: lines on where to look next.

The detailed view

$ euphoria analyze ~/Music/DJ/Intro.m4a
Intro.m4a
/Users/you/Music/DJ

  Key            10B  D major
                 runner up 9A  E minor
  Key in tags    9A  E minor
                 different key, differs from the detected key
                 The keys share few notes, so one reading is wrong or the track changes key.
                 Check by ear before you mix on it.
  Tempo          149.8 BPM
  Review         key may be its relative or a fifth away (runner up 9A  E minor), the tags say 9A
  Beat grid      first downbeat at 0.412 s, 149.82 BPM
                 ●●○ medium confidence
  Energy         6 of 10  ━━━━━━────
  Cues           A   0:00  Start      energy 3
                 B   0:16  Main       energy 7
                 C   1:18  Breakdown  energy 2
                 D   1:33  Drop       energy 7
  Sound quality  Weak on a big system
                 96 kbit/s. Fine for practice and small rooms; on a club system the top end and
                 detail suffer.
                 aac, 96 kbit/s, 44.1 kHz, stereo, sound stops at 15.4 kHz
  Loudness       -12.4 LUFS, true peak +1.0 dBTP
  Tuning         at concert pitch, A = 440 Hz
  Length         2:00

With --notes, a Notes row under the key shows how strongly each note sounds in the track, every octave together, from C to B: one bar each, over the note names, with a dot under the notes of the key.

  Notes          ▇  ▁  ▅  ▂  ▇  ▄  ▁  ▅  ▂  █  ▂  ▃
                 C  C# D  Eb E  F  F# G  Ab A  Bb B
                 •     •     •  •     •     •     •   • in the key, 8A

The marked bars should be the tallest. Reading the notes explains what to look for. A track analyzed before Euphoria measured notes says so; --reanalyze measures them.

One file analyzed on a terminal is always shown this way. --detail shows every track this way, whatever the output. The view names the runner up key, the key in the file’s tags with how it differs and which reading to trust, the half or double tempo when a DJ could count the track that way, why the track is worth checking by ear (or that you already checked it), the reason for the sound quality and the format behind it, the loudness, the beat grid with its confidence, each cue with its pad, its time and the energy of its section, the tuning, and the key changes when the key changes during the track. Cues you edited in the desktop app are listed with “set by you” and no energy. Cues analyzed before the energy of each section was measured have none, and the view says to analyze again with --reanalyze.

The plain table

Into a pipe or a file, the table has fixed columns and no colour:

$ euphoria analyze ~/Music/DJ | cat
Key             BPM  Energy  Quality   Time  File
8A   A minor  124.0       6  Lossless  6:48  /Users/you/Music/DJ/Low Tide.flac
10B  D major  149.8       6  Weak      2:00  /Users/you/Music/DJ/Intro.m4a

The plain table has no confidence column; scripts that need the ratings read confidence and bpm_confidence from --json. The summary still goes to standard error, so piped output holds only the table.

The tuning of a track and its key over time are in the detailed view and the JSON output.

Options

Option Effect
--json Print a JSON array instead of a table.
--detail Show every track in the detailed view. Cannot be combined with --json.
--notes Add to the detailed view the 12 notes the key analysis heard, as a row of bars with the notes of the key marked. Shows every track in detail. Cannot be combined with --json, which always has them.
--needs-review List only the tracks whose key is rated low confidence (it may be its relative or a fifth away), or whose tempo has a plausible half or double in the --tempo-range and is rated low or has onsets that back that octave more strongly, or whose tags name another key, and the files that could not be analyzed. A key or tempo you set or confirmed with Looks right in the desktop app is no longer in doubt, so such a track is not listed for it.
--bpm <RANGE> List only the tracks in a tempo range, in beats per minute: 120-126, 120- for 120 and faster, -126 for 126 and slower, or one tempo. A comma works as a decimal point: 120,5-126. Tempos from 30 to 300. The tempo is the one shown, so a tempo you set yourself is used and a detected one is in the --tempo-range.
--half-double With --bpm, also list the tracks at half or double a tempo in the range: --bpm 120-126 --half-double lists a track at 61 or at 244 too.
--energy <RANGE> List only the tracks in an energy range from 1 to 10: 6-8, 6- for 6 and more, -8 for 8 and less, or one rating. An energy you set yourself is used.
--stage <STAGE> List only the tracks at these set stages, separated by commas: warm-up, build or peak. The stage is placed among the tracks analyzed in the same run, so it needs at least 10 tracks with a tempo; with fewer, no track has a stage and none is listed. A tempo you set yourself is used. There is no closing stage.
--quality <QUALITY> List only the tracks with one of these sound qualities, separated by commas: lossless, limited, good, acceptable, weak or reencoded. weak,reencoded finds the files worth replacing. Combined with the other filters, a track must match all of them.
--key-notation <NOTATION> How keys are shown in the terminal table and the detailed view: camelot (the default), musical or open-key. The plain table follows it in its first column; JSON is unchanged.
--color <WHEN> auto (the default), always or never. See colour.
--verbose Keep the technical detail in error messages, such as the decoder’s own reason a file cannot be read. Works before or after any command.
--tempo-range <SLOWEST-FASTEST> Report tempos from SLOWEST up to, not including, FASTEST beats per minute, such as 70-140 for hip hop or 120-200 for drum and bass. The default is 90-180. FASTEST can be at most twice SLOWEST. See choosing the range.
-j, --jobs <N> Analyze N files at once, at least 1. The default is the number of cores, at most 8.
--audio-budget <MINUTES> Hold at most MINUTES of audio in memory at once, over all files being analyzed. The default is 60. See memory.
--no-cache Analyze every file, and neither read nor update the cache.
--reanalyze Analyze every file again and replace its cached result. Cannot be combined with --no-cache.
-h, --help Show help.
-V, --version Show the version.

A tempo is stored as it was estimated and placed in the range when it is shown, so running again with another --tempo-range takes every result from the cache. A tempo with no octave inside a range narrower than an octave, such as 105 BPM with 120-200, is shown at the octave nearest to the range, here 210.

Memory and long files

Analyzing one seven minute track peaks near 0.6 GB of memory, about 86 MB for each minute of audio. On full length tracks, 4 workers peaked near 2 GB in total and 8 workers between 4.8 and 6.2 GB, which is why the default stops at 8 workers. Lower --jobs on a machine with 8 GB of memory or less.

A count of workers does not bound memory when the files are long, so analysis also limits the audio in flight. Before a file is decoded, its length is read from its header, or estimated from its size when the header has none. The file waits until the minutes already being analyzed plus its own fit in --audio-budget, 60 minutes by default, about 5 GB. Seven minute tracks never meet the limit with 8 workers. Eight one hour mixes meet it, and run one at a time. A single file longer than the budget is analyzed alone, and still needs memory for its whole length, about 5 GB for one hour: give a computer with little memory shorter files or a lower budget with fewer workers. Key, tempo and energy are not yet measured on an excerpt of a very long file.

JSON output

Every object has "schema_version": 1, as the JSON of euphoria set build and euphoria plan does. Fields are only added within a schema version, never renamed or removed, so a script that reads a field keeps working; a change that breaks one raises the version. The review_reasons and reviewed fields, tempo_move of set build and plan, euphoria next, euphoria mashup and euphoria quality were added to version 1 this way. needs_review is now true exactly when review_reasons is not empty, so a track whose doubtful values you confirmed with Looks right reads false, as in the app. Paths are printed as given on the command line for analyze, and as absolute paths for set build.

One object per file, in path order, including files that failed, then one for each unreadable folder and skipped file:

[
  {
    "path": "/Users/you/Music/DJ/Low Tide.flac",
    "duration_seconds": 408.4,
    "key": { "camelot": "8A", "name": "A minor", "open_key": "1m", "confidence": "high" },
    "runner_up_key": { "camelot": "8B", "name": "C major", "open_key": "1d" },
    "tag_key": { "text": "8A", "key": { "camelot": "8A", "name": "A minor", "open_key": "1m" }, "agreement": "same" },
    "bpm": 170.0,
    "bpm_confidence": "medium",
    "bpm_alternative": 85.0,
    "energy": 6,
    "stage": "peak",
    "tuning_cents": -31.3,
    "pitch_class_profile": [0.812, 0.03, 0.5, 0.1, 0.8, 0.4, 0.05, 0.6, 0.1, 1.0, 0.15, 0.3],
    "key_timeline": [
      {
        "start_seconds": 0.0,
        "end_seconds": 250.0,
        "key": { "camelot": "8A", "name": "A minor", "open_key": "1m" }
      },
      {
        "start_seconds": 250.0,
        "end_seconds": 408.4,
        "key": { "camelot": "9A", "name": "E minor", "open_key": "2m" }
      }
    ],
    "beat_grid": { "first_downbeat_seconds": 0.372, "bpm": 170.004, "confidence": "high" },
    "cues": [
      { "seconds": 0.372, "name": "Start", "hot_cue": "A", "energy": 4 },
      { "seconds": 45.548, "name": "Main", "hot_cue": "B", "energy": 8 },
      { "seconds": 181.077, "name": "Breakdown", "hot_cue": "C", "energy": 3 },
      { "seconds": 226.249, "name": "Drop", "hot_cue": "D", "energy": 9 },
      { "seconds": 361.775, "name": "Outro", "hot_cue": "E", "energy": 5 }
    ],
    "loops": [
      { "start_seconds": 181.077, "end_seconds": 192.373, "name": "Loop 1" }
    ],
    "needs_review": false,
    "review_reasons": [],
    "reviewed": false,
    "set_by_user": [],
    "quality": {
      "codec": "flac",
      "lossless": true,
      "bitrate_kbps": 912,
      "sample_rate": 44100,
      "bit_depth": 16,
      "channels": 2,
      "cutoff_hz": null,
      "clipped_share": 0.0,
      "integrated_loudness_lufs": -8.4,
      "true_peak_dbtp": -0.3,
      "verdict": "lossless",
      "reason": "Lossless FLAC with a full spectrum."
    },
    "error": null
  },
  {
    "path": "/Users/you/Music/DJ/notes.txt",
    "duration_seconds": null,
    "key": null,
    "runner_up_key": null,
    "tag_key": null,
    "bpm": null,
    "bpm_confidence": null,
    "bpm_alternative": null,
    "energy": null,
    "tuning_cents": null,
    "pitch_class_profile": null,
    "key_timeline": [],
    "beat_grid": null,
    "cues": [],
    "loops": [],
    "needs_review": null,
    "review_reasons": [],
    "reviewed": null,
    "set_by_user": [],
    "quality": null,
    "error": "cannot decode /Users/you/Music/DJ/notes.txt: unsupported format: unsupported feature: core (probe): no suitable format reader found"
  }
]

After the files come entries for what the scan left out. A folder that could not be read has "unreadable": true, its path, and an error with the reason. An audio file of a format Euphoria cannot decode yet, found in a folder, has "skipped": true and an error. Both fields are absent from every other entry, and neither entry has an analysis.

review_reasons lists why the track is worth checking by ear, as the app’s Needs review does: key_unsure (the key is rated low), tempo_unsure (bpm_alternative is not null, and bpm_confidence is low or the onsets repeat more strongly after a beat and a bar of the alternative than of bpm, so the track may be counted in the wrong octave) and key_conflict (the tags name another key), in that order. It is empty for a track that is fine and for one whose doubts you settled, and for a file that failed, which has an error instead. reviewed is true when you set or confirmed the key or the tempo of the track in the app, and null for a file that failed.

key, bpm and energy are null when nothing was detected. energy is a whole number from 1 to 10. stage is "warm-up", "build" or "peak", the set stage among the tracks analyzed in the same run, and null for a track without a tempo and when fewer than 10 tracks have one; it is not the energy. The field was added to version 1 this way. error is set only when the file could not be analyzed. A file that is no longer there also has "missing": true; the field is absent on every other file.

A key is written with its Camelot code, its name and its Open Key code. The key of the track also has a confidence of high, medium or low; the keys of the timeline and the runner up have none. runner_up_key is the key that matched the track second best, which is the right key for many tracks whose detected key is wrong, and often the relative key or a key a fifth away. It is null when there is no key, and in builds without the drone feature.

bpm is reported in the --tempo-range, and bpm_confidence rates how sure the beat itself is, whatever octave it is counted in. bpm_alternative is half or double bpm when a DJ could plausibly count the track that way, between 75 and 200 BPM or the ends of the range when those are further out, and null otherwise. With the default range that is half of a tempo from 150 up and double of one up to 100, where tempo detection most often lands an octave off.

tag_key is the key field of the file’s tags, or null when the file has none or it is empty. text is the field as written. key is the key it names, or null when the text is not a key Euphoria reads. agreement compares it with the key of the track: same, fifth, relative, parallel, other, or unreadable when key is null; it is null when no key was detected. The tags are read fresh on every run, since other programs change them, and are never written by analyze.

needs_review is true when review_reasons has key_unsure or tempo_unsure, or the tags name another key, false otherwise, and null for a file that could not be analyzed. A value you corrected is no longer doubtful, so it does not count.

set_by_user lists the values you corrected or edited in the desktop app, any of "key", "bpm", "energy" and "cues", and is empty otherwise. A corrected key has no confidence and no runner_up_key, and a corrected tempo no bpm_confidence and no bpm_alternative: they rate what was detected, which is no longer shown. A corrected tempo also has no beat_grid, and none of the cues analysis placed, since both were fitted to the detected tempo; cues you edited stay.

tuning_cents is how far the track is tuned from A = 440 Hz, in cents from -50 to 50, where 100 cents is a semitone. Positive is sharp: at 30 the A above middle C sounds at 447.7 Hz, and at -31.3 at 432.1 Hz. It is null when the tuning could not be measured, which is the case for silence, for noise and for many tracks that are mostly drums. When it is 20 or more either way, the key is detected after bringing the track back to 440 Hz, so key names the nearest key at concert pitch.

pitch_class_profile is how strongly each of the 12 notes sounds in the track, every octave together, from C to B, C first: 12 numbers from 0 to 1 with the loudest note at 1. It is measured on Euphoria’s note spectrum, on the scale of the measured tuning (see the pitch-class profile). It is null for a track with no key, and for a track analyzed before Euphoria measured notes, until it is analyzed again.

key_timeline is the key over time, as sections in order that together cover the track from its start to duration_seconds, except where the track is silent. Silence has no key, so it belongs to no section: a track with silence in the middle has a gap between two sections there, and one that starts or ends in silence has a first section that starts late or a last one that ends early. A track in which no change of key was found has one section in the key of the track, or one on each side of every silence, all in that key. A track with no key has none. A passage with sound but no harmony, such as a drum break, is not silence and keeps the key of the music around it. The timeline stays in key and shows another key only for a stretch of at least about 30 seconds, with no silence in it, where that key is clearly stronger, so on dance music most tracks have one section and key is one of the sections. Section boundaries are accurate to a few seconds.

beat_grid places every beat and bar of the track with one constant tempo: first_downbeat_seconds is the time of the first beat of the first bar, from 0 up to the length of one bar, and bpm the tempo of the grid, in the --tempo-range like bpm, to a thousandth. When the grid is rated medium or high, bpm of the track is this tempo, and it is a whole number whenever a grid at the whole number fits the beats as well, so the table, the tags, the exports and the grid agree. A grid rated low, as for a live recording whose tempo drifts, leaves bpm at the tempo detector’s estimate, and its own tempo can differ from it by up to 2%. Every following beat falls 60 / bpm seconds after the one before, and every fourth beat starts a bar. confidence rates how far to trust the beats, not the choice of downbeat, which is right less often. beat_grid is null when the track has no tempo. The grid is not shown in the table. See beat grid.

cues lists the cues of the track in order: seconds from the start of the track, to a thousandth, name, hot_cue, the hot cue pad from "A" to "H", or null for a memory cue only, and energy, the energy rating of the section from the cue to the next one, from 1 to 10, or null for a cue you edited, a silent section, or a track analyzed before it was measured. The cues analysis placed mark where the sections of the track start, named Start, Main, Breakdown, Drop and Outro, each on the first beat of a bar of beat_grid at a phrase boundary, on pads from A in order, at most 8. They are empty when the track has no beat grid. See cue points. When you edited the cues of a track in the desktop app, cues lists yours instead, with the names and pads you gave them, and set_by_user includes "cues"; an empty list then means you deleted every cue.

loops lists the loops you saved in the desktop app, in order of their start: start_seconds and end_seconds from the start of the track, to a thousandth, and name. It is empty when you saved none. Saved loops do not change the cues, so they are not in set_by_user.

Accuracy describes how both are measured and how far to trust them, and confidence how the ratings, the runner up and the alternative tempo were set and how often they are right.

quality is the audio quality report, or null for a file that could not be analyzed:

Field Meaning
codec The audio codec, such as mp3, aac, flac, alac or pcm_s16le.
lossless Whether the codec keeps every bit.
bitrate_kbps The average bit rate of the audio data in kbit/s, measured from the audio packets.
sample_rate, bit_depth, channels As the file declares them. bit_depth is null for lossy files.
cutoff_hz The frequency where the content stops, or null when it reaches the top of the spectrum.
clipped_share The share of samples in runs of three or more at full scale, from 0 to 1.
integrated_loudness_lufs Integrated loudness, as EBU R128 describes, on the mono mixdown. null for silence.
true_peak_dbtp The highest true peak in any channel, in dB relative to full scale.
verdict lossless, limited-bandwidth, good, acceptable, weak-on-a-big-system or likely-reencoded. limited-bandwidth is new: a lossless file whose content stops below 19 kHz with a gradual roll-off, which earlier versions reported as likely-reencoded. A script that counts likely-reencoded among lossless files now sees fewer; no other field or value changed.
reason One or two sentences that explain the verdict.
damaged true when packets could not be decoded or the audio is shorter than the file declares. See damaged files.
damage The numbers behind damaged: dropped_packets, concealed_seconds (silence put in place of dropped packets), ended_on_error, declared_seconds (null when the file declares no length) and decoded_seconds.
notes Sentences about damage and about stereo channels that cancelled in the mono mixdown. Empty for a sound file.
cancelled_share The share of a stereo file, from 0 to 1, whose channels cancelled in the mono mixdown, so the left channel was analyzed there.

Progress and exit status

When standard error is a terminal, the command first says where it looks, for example Looking for audio files in ~/Music/DJ tracks, or ... in ~/Music/DJ tracks and 2 more when given several paths, with your home folder written as ~ and a long path cut in the middle so the folder at its end stays in view. Then each file being analyzed has a line with a spinner and the stage it is in: decoding, with how much is decoded, then finding the tempo, finding the key, rating the energy, finding the beat grid and checking the quality. After five seconds the line also shows how long the file has taken, so a long track never looks stuck. With more than one file, a bar above the lines counts the finished files and estimates the time left. Files served from the cache get no line. Nothing of this is written when standard error is not a terminal.

A debug build analyzes many times slower than a release build. When a run of a debug build has taken ten seconds, it says so once on standard error. Release builds never do.

When some results came from the cache, a line such as 120 of 124 tracks came from the cache. is written to standard error, so piped output holds only the table or the JSON.

The exit status is 0 when every file was analyzed, 1 when any file failed, and 3 when the only problem is files that are missing, folders that could not be read, or a path that holds no audio file. A folder that is empty, or holds only other files, prints warning: no audio files found. and exits with status 3, so a script sees a mistyped or unmounted path. When no file could be analyzed, such as when every path is missing, no table header is printed.

The command exits with status 0 when every file was analyzed. If any file failed, each one is listed on standard error as error: <path>: <reason> after the table, and the command exits with status 1. It also exits with status 1, after printing the results, if saving them to the cache failed partway through the run. A cache that cannot be used at all only causes a warning and does not change the exit status.

A folder inside a path you gave that cannot be read, because its permission is denied or a network drive fails, no longer stops the scan. The command goes on with everything else, and writes a warning with a count and the reason for each folder, after the table:

warning: 2 folders could not be read: /Volumes/NAS/Crates/Old, /Volumes/NAS/Crates/Locked
  /Volumes/NAS/Crates/Old: Input/output error (os error 5)
  /Volumes/NAS/Crates/Locked: Permission denied (os error 13)
hint: The files in them were not analyzed. Fix the permissions or reconnect the drive, then run the command again.

The files in those folders were not analyzed, so when folders could not be read and nothing failed the command exits with status 3, as for missing files. Status 1 still wins when a file failed. The same warning and exit status apply to euphoria tags write, euphoria tags set, euphoria export and euphoria set, which scan folders in the same way. A path named on the command line that cannot be examined at all is still an error.

Files in a folder with an extension for audio that Euphoria cannot decode yet (.opus, .wma, .wv, .ape, .dsf, .dff, .mpc, .tta, .aac, .ac3, .dts, .amr, .mka, .mp2, .oga, .webm and .caf) are counted by extension and reported in one warning, which does not change the exit status:

warning: 14 files skipped: 9 .opus, 5 .wma, which Euphoria can't decode yet

Pictures, playlists and other files that are not audio are not counted.

A file that cannot be read as audio is listed as error: <path>: cannot be read as audio (not a supported or valid audio file). The decoder’s own reason is kept behind --verbose.

A file that is no longer there, because it was moved, deleted, or is on a drive that is not connected, is not a failure. It is listed after the errors as missing: <path>, followed by a count, and when files are missing and nothing failed the command exits with status 3, even when every file named is missing. A path named on the command line that does not exist is reported this way, and the other paths are still analyzed:

missing: /Volumes/USB/Crates/Low Tide.flac
1 file is missing: moved, deleted, or on a drive that is not connected.

euphoria export rekordbox

Analyzes audio files and writes the results as a rekordbox XML file, which rekordbox imports with keys, tempos and playlists. Export to rekordbox walks through the export and the import.

euphoria export rekordbox [OPTIONS] --output <FILE> <PATHS>...
euphoria export rekordbox [OPTIONS] --output <FILE> --playlist <NAME>

Paths are searched as in euphoria analyze, and results come from the cache when the tracks were analyzed before. Each path is turned into a full path first, taken from the current directory when it is relative, with any symbolic link in it followed, because rekordbox finds tracks by their full path.

$ euphoria export rekordbox ~/Music/DJ --output ~/Music/euphoria.xml
Exported 340 tracks in 12 playlists to /Users/you/Music/euphoria.xml (336 from the cache)
To import it in rekordbox:
  1. Preferences > View > Layout: tick rekordbox xml.
  2. Preferences > Advanced > Database: choose this file.
  3. Refresh rekordbox xml in the tree, then import its tracks or playlists.
Full guide: https://github.com/lvndry/euphoria/blob/main/docs/guides/export-to-rekordbox.md

Options

Option Effect
-o, --output <FILE> The file to write. Required.
--force Replace the output file if it exists. Without it, an existing file is an error and nothing is analyzed.
--key-notation <NOTATION> camelot (the default) writes keys such as 8A, musical writes keys such as Am, open-key writes keys such as 1m.
--no-playlists Write the tracks only, without playlists.
--beat-grid Write each track’s beat grid, except grids rated low confidence. See beat grids.
--playlist <NAME> Export a playlist built in the desktop app in place of paths: its tracks, and one playlist in its order. The name is matched ignoring case; euphoria playlists lists them. Each file is read and compared with the track that was added; one that is no longer anywhere, or that was replaced at its path by other audio, is left out with a warning. Cannot be combined with paths or --no-playlists.
--cues Write each track’s cue points as memory cues and hot cues, on tracks whose beat grid is written, or the cues you edited in the desktop app in their place, and the loops you saved in the app as memory loops. Needs --beat-grid and --collection. See cue points.
--collection <FILE> Your rekordbox collection exported as XML. Needs --beat-grid. Tracks there with a constant beat grid are exported with that grid and their cues on its bars: see use your rekordbox beat grid. With --cues, tracks that have cues or loops there are also left out of the file. It is never replaced by the export, even with --force.
--cue-colors <COLOURS> energy (the default) colours each hot cue analysis placed by the energy of its section, from blue for calm to red for intense; fixed writes no colour, so rekordbox uses its own. Needs --cues.
--allow-unmatched-cued-tracks Export even though some tracks with cues in the collection match no file on this computer. See cue points.
--tempo-range <SLOWEST-FASTEST> The range tempos are written in, 90-180 by default, as for euphoria analyze.
-j, --jobs <N> Analyze N files at once. The default is the number of cores, at most 8.
--no-cache Analyze every file, and neither read nor update the cache.
--reanalyze Analyze every file again and replace its cached result. Cannot be combined with --no-cache.
-h, --help Show help.

What is written

Each track has its full path, its duration, its key and tempo when Euphoria found them, its energy rating as the comment Energy 7 when it has one, and its title and artist. Title and artist are read from the file’s own tags: ID3 in MP3 and AIFF, Vorbis comments in FLAC, MP4 metadata in M4A and the INFO list in WAV. A file with no title is given its file name without the extension. So is a file whose tags cannot be read, which is exported without an artist.

Playlists mirror the folders:

  • Each folder named on the command line becomes one entry at the top level, in the order given.
  • A folder holding only tracks becomes a playlist. A folder holding other folders with tracks becomes a playlist folder, and tracks sitting directly in it go into a playlist of the same name, first inside it.
  • A folder with no tracks anywhere inside is left out.
  • Files named directly go into one last playlist, named after the output file without its extension.
  • When one named folder is inside another, each gets its own entry.
  • An entry that would have the same name as an earlier entry beside it gets (2), (3) and so on after its name.

Beat grids

With --beat-grid, a track whose beat grid is rated medium or high gets it in the file, as its first downbeat and its tempo with two decimals; that tempo is then the track’s tempo in the file too. Rounding to two decimals changes the tempo by at most 0.005 BPM, which moves a beat T seconds into the track by at most T × 0.005 / BPM seconds. At the end of a seven minute track, T = 420, that is 2.1 / BPM seconds: 23 ms at 90 BPM, 16 ms at 128 BPM and 12 ms at 180 BPM, or 30 ms at 70 BPM with --tempo-range 70-140. A track whose grid is rated low, or that has none, is written without one, and rekordbox draws its own grid when it analyzes the track. A line on standard error says how many tracks got a grid:

Beat grids for 312 of 340 tracks; the others have no clear beat or a grid rated low confidence, so rekordbox analyzes them.

Import To Collection of a track that is already in your collection replaces its key, tempo and comment with the ones in the file (tested in rekordbox 7.2.19). Expect it to replace a grid you adjusted by hand in rekordbox too; that was not tested. Read export to rekordbox before importing tracks you have already prepared.

Cue points

With --cues, each track whose beat grid is written also gets its cues, each twice: as a memory cue and as a hot cue, on pads from A in order. Cues are off unless asked for. Each hot cue gets the colour of the energy of its section as Red, Green and Blue, unless --cue-colors fixed; memory cues get no colour.

A track whose cues you edited in the desktop app gets yours instead, with your names: each as a memory cue, and also as a hot cue on its pad when it has one. Your cues are exported whether or not the track’s beat grid is, since you placed them yourself, and a track whose cues you all deleted gets none. The rule below still applies: a track with cues of its own in your rekordbox collection is left out, whatever cues you edited in Euphoria.

Euphoria never changes the cues of a track that already has some of its own in rekordbox. --cues therefore needs --collection, naming your collection exported from rekordbox with File > Export Collection in xml format. A track listed there with any cue, hot cue or loop is left out of the file entirely, from the collection and from every playlist. Import To Collection replaces what rekordbox has for a track with what the file says, and was not tested on cues, so leaving such a track out is the only way to be sure no import of the file can change its cues. Export again without --cues to update the key and tempo of those tracks. Standard error gives the counts:

Cues for 296 of 324 tracks; tracks without a beat grid in the file get none, unless you edited their cues in the app.
Left out 16 tracks that already have cues in your rekordbox collection, so importing this file cannot change them. Export again without --cues to update their key and tempo.

When every track already has cues, nothing is written and the command exits with status 1.

A track with cues in the collection is recognised by its file. When such a track matches no file on this computer, because it has no location, its location is not a local file, or no file is at its path (a collection exported on another computer, a moved or deleted file, a drive that is not mounted), Euphoria cannot tell whether it is one of the tracks being exported and so cannot protect its cues. The export then stops before analyzing anything, lists those tracks by title, artist and location, and writes nothing. Export the collection from rekordbox on this computer, or relocate or remove those tracks in rekordbox. If none of them is a track you are exporting, pass --allow-unmatched-cued-tracks: the export goes ahead and lists them again under “Not protected”.

The output file is never the collection file, however either path is written, through a symbolic link, with . or .., or another spelling of the same file, and --force does not change this.

The file is written under a temporary name in the folder of the output file and moved into place once it is complete, so the output file is never half written. Without --force it only takes a name that is free: a file that another program creates at the output path while the export runs is kept, and the export fails.

Output and exit status

Nothing is written to standard output. Standard error gets the progress when it is a terminal, one line saying how many tracks and playlists were exported and where, with --beat-grid one line saying how many got a grid, with --cues one line saying how many got cues, and the steps to import the file into rekordbox. The summary ends with how many tracks came from the cache when some did.

Only a file that could not be analyzed is left out of the export. Such files are listed on standard error with the reason, before the summary, and the command exits with status 1 after writing the file for the other tracks:

error: /Users/you/Music/DJ/notes.txt: cannot decode /Users/you/Music/DJ/notes.txt: unsupported format: unsupported feature: core (probe): no suitable format reader found
Exported 339 tracks in 12 playlists to /Users/you/Music/euphoria.xml
Left 1 file out of the export; the errors above say why.

A track whose key and tempo are known but whose tags cannot be read is still exported, under its file name and without an artist. This happens when the result came from the cache and the file can no longer be opened, for example after its permissions changed. Such tracks are listed as warnings before the summary, and a warning alone does not change the exit status:

warning: /Users/you/Music/DJ/Low Tide.flac: named after its file, as its title could not be read: cannot open /Users/you/Music/DJ/Low Tide.flac: Permission denied (os error 13)
Exported 340 tracks in 12 playlists to /Users/you/Music/euphoria.xml (340 from the cache)

A damaged tag does not cause the warning. Either the file still opens and is exported under its file name, or the damage stops the file from being decoded and it is listed as left out.

The command also exits with status 1, and writes no file, when:

  • the output file exists and --force was not given, or its folder does not exist,
  • the output file is one of the audio files to export, reached by any path or symbolic link, or it has an audio file extension and is inside a folder to export. --force does not change this, so an export never replaces a track,
  • no audio file was found, or none could be exported,
  • a file or folder to export does not exist; the error says it is missing,
  • folders are nested more than 32 levels deep, the most a rekordbox XML file can hold. The error names the first folder beyond the limit.

With --playlist, a track of the playlist that is no longer anywhere, even where the cache last saw it, is left out and listed as missing: <path>; when tracks are missing and nothing failed, the command exits with status 3. A track whose path now holds other audio is left out with a warning, and the command exits with status 1. A file that disappears while the export runs is listed as missing in the same way. When every track of the playlist is missing, nothing is exported and the exit status is 1, as when no audio file is found.

As with euphoria analyze, a cache that cannot be used only causes a warning, and a failure to save results to the cache partway through gives status 1 after the file is written.

euphoria export traktor

Analyzes audio files and writes the results as a Traktor collection file (NML), which Traktor Pro imports with Import Another Collection. Export to Traktor walks through the import. Not tested in Traktor.

euphoria export traktor [OPTIONS] --output <FILE> <PATHS>...
euphoria export traktor [OPTIONS] --output <FILE> --playlist <NAME>

It works as euphoria export rekordbox does: the same paths, cache, playlists per folder, --playlist, refusals, exit status and temporary file. The differences:

Option Effect
--key-notation <NOTATION> camelot (the default), musical or open-key, for the Key Text column. The Key column is filled from the key itself.
--beat-grid A grid marker at each track’s first downbeat, with the grid’s tempo in six decimals, except grids rated low confidence.
--cues Hot cues 1 to 8 at each track’s sections, on tracks whose grid is written, and the loops you saved in the app as loops. No memory copy of each hot cue is added. Needs --beat-grid and --collection. They are not coloured by energy, and there is no --cue-colors: Traktor colours a cue by its type.
--collection <FILE> Your Traktor collection.nml, only read. Tracks with a cue, hot cue or loop of their own there are left out of the file. Grid markers and Traktor’s AutoGrid hot cue on a grid marker do not count. It is never replaced, even with --force.
--startup-volume <NAME> The name of the Mac disk the system is on, which Traktor writes as the volume of every path outside /Volumes. Found from /Volumes when not given.

Each track has its location as volume, folders and file, its title and artist from its tags, its duration, its key in INFO KEY and MUSICAL_KEY, its tempo, and its energy rating as the comment Energy 7. A path that is not valid Unicode cannot be written in the file and is an error. Two paths that name the same file to Traktor, such as /a.mp3 and /Volumes/Macintosh HD/a.mp3, are an error too.

euphoria export engine

Analyzes audio files and writes the results into the tracks of your Engine DJ library, Engine Library/Database2/m.db, after saving a copy of it. Export to Engine DJ explains what is written, what is kept and why it is safe to the extent it is. Not tested in Engine DJ.

euphoria export engine [OPTIONS] <PATHS>...
euphoria export engine [OPTIONS] --playlist <NAME>

Tracks are matched by the path Engine DJ stores. It refuses to write while Engine DJ is running, when a journal holds an unfinished write, and for a schema version other than 2.18.0 to 3.0.2 (Engine DJ 2.0 to 5.0). These checks run before the analysis.

Option Effect
--library <FOLDER> The Engine Library folder. Music/Engine Library in your home folder when not given.
--label <WHERE> Where the key and energy label goes in the comment: comment-start (the default), comment-end or none.
--key-notation <NOTATION> camelot (the default), musical or open-key, for the label.
--beat-grid A constant grid from each track’s first downbeat, on tracks Engine DJ has analysed, except grids rated low confidence.
--cues Hot cues 1 to 8 at each track’s sections, on tracks Engine DJ has analysed and that have no hot cues of their own. Needs --beat-grid.
--cue-colors <COLOURS> energy (the default) gives each cue analysis placed the Engine DJ pad colour nearest to the energy of its section; fixed gives each cue the colour of its pad. Needs --cues.
--dry-run Checks the library and says what would change, writing nothing. Cannot be combined with --yes.
-y, --yes Write without asking for confirmation.

Before anything is written the command says how many tracks will be updated, in which library, and lists the first ten. It then asks Write N tracks into <library>? A copy is saved first. [y/N]. Only y or yes writes. When standard input is not a terminal and --yes was not given, it writes nothing, says error: nothing was written with a hint, and exits with status 1. A running Engine DJ still stops the command before the analysis, with or without --yes.

The copy is saved as Engine Library backup by Euphoria <date> <time>/Database2/m.db next to the library. The exit status is 1 when no track is in the library, a file could not be analyzed, or a track of --playlist now holds other audio at its path; it is 3 when tracks are missing and nothing else failed, as for euphoria export rekordbox. When every track of --playlist is missing, nothing is exported and the exit status is 1.

euphoria export virtualdj

Analyzes audio files and writes the results into the songs of your VirtualDJ database.xml, after saving a copy of it. Export to VirtualDJ explains what is written and kept. Not tested in VirtualDJ.

euphoria export virtualdj [OPTIONS] <PATHS>...
euphoria export virtualdj [OPTIONS] --playlist <NAME>

Songs are matched by path, and only songs the database holds are changed. Every other byte of the file is kept. It refuses to write while VirtualDJ is running.

Option Effect
--database <FILE> The database.xml to update. Found in your home folder when not given; tracks on another drive are in VirtualDJ/database.xml on that drive.
--label <WHERE> Where the key and energy label goes: comment-start (the default), comment-end, grouping or none. The text already there is kept.
--key-notation <NOTATION> camelot (the default), musical or open-key, for the label. The Key attributes are musical names, which VirtualDJ shows in its own notation.
--beat-grid The grid anchor at each track’s first downbeat, except grids rated low confidence.
--cues Hot cues 1 to 8 at each track’s sections, on tracks whose grid is written, for songs with no cues of their own. Needs --beat-grid.
--cue-colors <COLOURS> energy (the default) writes the colour of the energy of each section as Color of each cue analysis placed; fixed writes none, so VirtualDJ uses its own. Needs --cues.
--dry-run Says what would change and writes nothing. Cannot be combined with --yes.
-y, --yes Write without asking for confirmation.

Before anything is written the command says how many songs will be updated and lists the first ten, then asks Write N tracks into <database>? A copy is saved first. [y/N]. Only y or yes writes. When standard input is not a terminal and --yes was not given, it writes nothing, says error: nothing was written with a hint, and exits with status 1. A running VirtualDJ still stops the command, with or without --yes.

The copy is saved next to the database as database.xml.euphoria-backup-<date>-<time>. The exit status is 1 when no track is in the database, a file could not be analyzed, or a track of --playlist now holds other audio at its path; it is 3 when tracks are missing and nothing else failed, as for euphoria export rekordbox. When every track of --playlist is missing, nothing is exported and the exit status is 1.

euphoria export m3u8

Writes a playlist built in the desktop app as an M3U8 file, the playlist format nearly every DJ and music program opens: Serato, Traktor, Engine DJ, VirtualDJ, Mixxx and music players.

euphoria export m3u8 --playlist <NAME> --output <FILE> [--force] [--no-cache]
$ euphoria export m3u8 --playlist "Peak time" --output ~/Music/peak-time.m3u8
Exported 14 tracks of Peak time to /Users/you/Music/peak-time.m3u8

The file starts with #EXTM3U and #PLAYLIST: and the playlist’s name, then gives each track as an #EXTINF: line with its length in seconds and “Artist - Title” from its tags, followed by its full path, in UTF-8. A length the cache does not know is written as -1. Nothing is analyzed.

Option Effect
--playlist <NAME> The playlist, matched ignoring case. Required.
-o, --output <FILE> The file to write. Required.
--force Replace the output file if it exists.
--no-cache Neither look for files that moved where the cache last saw them, nor read lengths from it.

Each file is read and compared with the track that was added before it is exported. A track that is no longer anywhere is left out and listed as missing: <path>, and the command exits with status 3. A track whose file was replaced at its path by other audio is left out with a warning, and the command exits with status 1. When every track is missing, the file is written with no tracks and the exit status is 3. A path the format cannot hold, such as one with a line break in it, is an error and nothing is written. The file is written in one step, as for euphoria export rekordbox.

euphoria playlists

Lists the playlists built in the desktop app, in the app’s order, each with its label and how many tracks it holds:

$ euphoria playlists
🔥 Peak time  (14 tracks)
Warmup  (9 tracks)

Playlists are kept in playlists.sqlite3 beside the cache, each track by the content of its file and its last path, so euphoria cache clear leaves them as they are.

euphoria set build

Orders tracks from a pool into a set that follows an energy curve, with every transition an allowed key move and a small tempo step.

euphoria set build [OPTIONS] <FOLDER|PLAYLIST>...

The pool is folders or audio files, searched as euphoria analyze searches them, or the name of a playlist built in the desktop app when the one argument is not a path. Tracks are analyzed first or read from the cache, with your corrections applied. The guide explains the curve, the rules and how the set is chosen.

Option Meaning
--curve <CURVE> Energy levels from 1 to 10 separated by commas, spread evenly over the set, or a preset: warm-up, peak-time, journey (the default).
--tracks <COUNT> The length of the set. Defaults to 20.
--minutes <MINUTES> The length of the set in minutes, turned into a count by the median track length of the pool.
--first <FILE>, --last <FILE> Open or close the set with this track, which joins the pool if it is not in it.
--max-bpm-step <BPM> The largest tempo change between two tracks. Defaults to 5.
--moves <MOVES> The key moves allowed, separated by commas: same, adjacent, relative, diagonal, energy-boost, mood-change, semitone-boost. Defaults to the first five.
--allow-artist-repeats Let two tracks by the same artist follow each other.
--json Print JSON instead of the table.
--m3u <FILE> Also write the set as an M3U8 playlist, with the absolute path of every track, whether the pool was given as a relative path or not. --force replaces an existing file.
--key-notation <NOTATION> How keys are shown in the table.

The analysis options of euphoria analyze also apply: --jobs, --no-cache, --reanalyze and --tempo-range.

Standard output gets a table, one track per line, with the tempo step from the track before in beats per minute, the tempo move (Easy under 3 percent, Pitch move up to 6 percent, Big jump over, the words of the desktop app), the key move in the app’s words, the energy and the energy the curve asks for, then two rows of blocks that draw the curve and the set. Standard error gets a summary and a warning: for each place the set falls short of the curve or breaks a rule.

The JSON object has schema_version (1), tracks (position from 1, absolute path, artist, title, key, bpm, energy, target_energy, duration_seconds, pinned), transitions (from, to, key_move, key_move_allowed, bpm_change, bpm_change_percent, tempo_move, tempo_allowed, same_artist), deviations (each with a kind: short_pool, energy_off_target, key_clash, tempo_jump or repeated_artist, and the position it concerns), left_out (tracks without a key, tempo or energy), failed (files that could not be analyzed), mean_energy_error, every_transition_clean, cost and lower_bound.

The exit status is 0 when a set was built, even one with deviations, and 1 when none could be built, such as when no track of the pool has a key, a tempo and an energy.

euphoria set render

Renders a set as one continuous mix: each track blended into the next at a section start, beatmatched with its key kept, written as a WAV, FLAC or MP3 file.

euphoria set render [OPTIONS] <SET>...

SET is the name of a playlist built in the desktop app, an M3U or M3U8 playlist file, or audio files in play order. A folder is refused, since it has no order. Tracks are analyzed first or read from the cache, with your corrections applied. Each transition is the best window euphoria plan ranks that starts after the blend into the outgoing track has ended, unless you locked it in the desktop app’s planner, which keeps it as you placed it; a pair that cannot blend plays one after the other. Sections are read from the cues each track shows, your edited cues included. The guide explains where tracks come in and how a blend sounds.

Option Meaning
-o, --out <FILE> The mix to write, ending in .wav (24 bit, RF64 past 4 GB), .flac (24 bit) or .mp3. Required unless --dry-run. --output is the same.
--format <FORMAT> wav, flac or mp3. Defaults to the extension of --out; a name without one gets it added, and a name with the other one is refused.
--mp3-bitrate <KBPS> The constant bitrate of an MP3 mix: 96, 112, 128, 160, 192, 224, 256 or 320, the default. The MP3 is encoded by LAME, built in, and its ID3 tag holds a chapter per track.
--tracklist Also write NAME.tracklist.txt beside the mix: one numbered line per track with the time it starts.
--cue Also write NAME.cue beside the mix: a CUE sheet with each track’s title, artist and start.
--chapters Also write NAME.chapters.txt beside the mix: one line per track, 0:00 Artist - Title, for a video description.
--dry-run Print the plan, with a warning under every blend where both tracks sing, and write nothing.
--fix-vocals [FIX] Fix every blend where both tracks sing: move the blend to a window where only one sings, cut the outgoing vocals with its stems, or fade it out before the incoming one sings. Alone, the first fix that applies, in that order. Locked blends are never moved.
--force Replace the mix and the files beside it if they exist. Without it, an existing file is refused before anything is rendered.

The analysis options of euphoria analyze also apply: --jobs, --no-cache, --reanalyze and --tempo-range.

Standard output has the name of the set, its track count and length, then one line per track with the time it starts in the mix and under it, after ↳, why the transition into the next track is where it is. A transition played one after the other is shown in the caution colour. Standard error has a progress bar while rendering, then a line for each file written.

The exit status is 0 when the mix was written, or the plan printed with --dry-run, and 1 when a track cannot be analyzed or read, or a file cannot be written.

euphoria plan

Plans the mix from one track into the next: how B lines up with A, where the two clash, and the best windows to mix in.

euphoria plan [OPTIONS] <A> <B>

A is the track that is playing and B the one that follows. Both are analyzed first or read from the cache, with your corrections applied. The concept page explains how the plan is made and scored.

Energy over time and the levels of the stems take a moment to measure the first time, and are kept in a plan-signals folder beside the cache, named by the content of each file, so the next plan is instant. Stems are used when euphoria stems has already separated the track; plan never separates one. Without them vocals, bass and drums are unknown and clashes are not checked.

Option Meaning
--json Print JSON instead of the summary.

The analysis options of euphoria analyze also apply: --jobs, --no-cache, --reanalyze and --tempo-range.

Standard output has the tempo change of B with its label (Tempo B 125.0 to 128.4 BPM, played at 1.027x (+2.7%, Easy)) and the key move, then the top 3 windows. Each has its score, its sections and first bars, a strip of one cell per bar (█ both sing, ▄ both play bass, · no clash, ? not known), the reason for its rank and its steps. Last come the cues suggested for the best window, which are not written.

A window whose bars were not checked, because the stems of A or B are not cached, says (N of M bars not checked) after its score. Bars nobody checked earn no clash credit, so such a window scores at most 55 of 100, and a window with unchecked bars never ranks above one whose bars were all checked. When no window fits, the line says why: a track has fewer than 16 bars, or no bar of A that ends a phrase meets a section start of B with 16 bars left.

Numbers in the JSON are rounded: tempos to two decimals, every other number to three.

The JSON object has schema_version (1), a, b, elapsed_milliseconds, tempo_move (easy, pitch_move or big_jump for the tempo change of B) and plan: the alignment (bpm_a, bpm_b, rate, tempo_change_percent, bar_seconds), the bars of both tracks as lanes_a and lanes_b (section, energy, vocals, bass and drums per bar, each present, absent or unknown), up to 10 windows and the cues for the first one.

The exit status is 0 when a plan was made, even one with no window, and 1 when none could be, such as when a track has no beat grid or B cannot reach the tempo of A on a deck.

euphoria live

Shows the key and tempo of the audio playing on this Mac, as it plays. The analysis is the one of the Live window of the desktop app; the audio stays in memory and nothing is recorded, written or sent anywhere.

euphoria live [OPTIONS]

Needs macOS 14.2 or later, and macOS asks once to allow listening. One line is printed per reading, 8A A minor 124.0 BPM energy 6/10 steady, or listening… once while the audio is silent. Ctrl-C stops it.

Option Meaning
--source <PROCESS> Listen to one application, by the start of its name. Without it, everything playing is heard except Euphoria.
--interval <SECONDS> Seconds between readings, 0.5 or more. Default 2.
--from <FOLDER|FILE> Recognise which of these tracks plays, also when it is played up to 10 percent faster or slower. Their fingerprints are made once and kept in the cache, so the first run over a large folder takes a while. A recognised track ends the reading line with matched: <title>.
--json One JSON object per line: listening, source, key (camelot, name, confidence), bpm, bpm_confidence, energy, level_db, steady, and match (path, title, artist, position_seconds, tempo_ratio, pitch_follows_tempo, or null).

euphoria next

Ranks the best tracks to play after a track, the same ranking as the Next after list of the desktop app.

euphoria next [OPTIONS] <TRACK>

Candidates come from the folder of TRACK, or from --from. A candidate mixes in when its key is the same, one step on the wheel or the relative key, and its tempo is within 6 percent of the track’s; among those, the order follows the energy you ask for. Tracks are analyzed first or read from the cache, with your corrections applied, so a key, tempo or energy you set in the app is the one used. Keys and Camelot explains the ranking.

$ euphoria next "Low Tide.flac" --lift --limit 3
After Low Tide  8A  124.0 BPM  energy 6  lifting the energy
#  Key  BPM    Tempo        Move                   Energy  Track
1   8A  125.0  +0.8% Easy   Same key               8 ↑2    Night Drive.flac
2   9A  124.0  +0.0% Easy   One step on the wheel  7 ↑1    Glow.flac
3   8B  126.0  +1.6% Easy   Relative               6 =     Low Tide (Dub).flac
Option Effect
--from <FOLDER|PLAYLIST> Where to choose from: a folder, audio files or the name of a playlist built in the app. May be given more than once. Defaults to the folder of the track.
--lift Rank tracks with more energy first.
--drop Rank tracks with less energy first. Without --lift or --drop, tracks at the same energy come first (Keep in the app). They cannot be combined.
--limit <COUNT> How many tracks to list. Defaults to 10.
--json Print JSON instead of the table.
--bpm <RANGE>, --half-double, --energy <RANGE>, --quality <QUALITY> The filters of euphoria analyze, applied to the candidates. With --half-double, a candidate at half or double the tempo of the track counts as a tempo match too.
--key-notation <NOTATION> How keys are shown in the table.

The analysis options of euphoria analyze also apply: --jobs, --no-cache, --reanalyze and --tempo-range.

Each row has the key, the tempo, the tempo change as a percent with its move (Easy, Pitch move or Big jump), the key move in the shared words, and the energy with an arrow and the size of its change from the track’s: 3 ↓6 is 6 calmer, 8 ↑1 one higher, 7 = the same. The playing track is never listed. Starred transitions, which the app puts first, are not used by the command line.

The JSON object has schema_version (1), track (path, artist, title, key, key_name, bpm, energy), energy (keep, lift or drop) and next: one object per candidate with rank from 1, the same fields as track, key_move (same, adjacent, relative, diagonal, energy_boost, mood_change or semitone_boost, as in set build), key_move_label (the words), tempo_percent, tempo_move (easy, pitch_move or big_jump), tempo_scaling (direct, half or double) and energy_change. Tempo and energy fields are null when a track has none.

The exit status is 0 when the ranking was made, even when no track mixes in, and 1 when the track could not be analyzed. A note on standard error says why a list is empty or short.

euphoria quality

Lists the files whose audio is too poor for a club system, worst first, each with a plain reason, so you can buy or download a better copy. The verdicts are the audio quality verdicts of euphoria analyze; tracks analyzed before are read from the cache and not decoded again.

euphoria quality [OPTIONS] <PATHS>...
$ euphoria quality ~/Music/DJ
3 of 212 tracks to replace: 1 heavily damaged, 1 fake lossless, 1 low bit rate.

Heavily damaged  Saffron & Co - Low Tide
  Good: 41.2 s missing at the end
  Deep/Low Tide.mp3

Fake lossless    Harbour Lights - Night Drive
  Likely re-encoded: FLAC, but the sound stops at 16.1 kHz like a 128 kbit/s MP3
  Club/Night Drive.flac

Low bit rate     Glow - Afterglow
  Weak on a big system: MP3, 128 kbit/s; 0.42% of the samples clipped at full scale
  Afterglow.mp3

The first line counts the tracks and the files to replace by their worst problem. Each file then has a block: its worst problem and its artist and title from the tags (the file name when it has none), its verdict with a concrete reason for each problem, and its path relative to the folder given. A file is listed for these problems, in this order:

Problem When
Heavily damaged 2% or more of the audio could not be decoded or is missing, so the beat grid and cues are not written. See damaged files.
Fake lossless A lossless file whose sound stops in a brick wall, where a lossy file’s would: verdict Likely re-encoded.
Re-encoded A lossy file whose sound stops where a lower bit rate file’s would: verdict Likely re-encoded.
Low bit rate Verdict Weak on a big system.
Damaged Some audio could not be decoded or is missing, less than 2%.
Medium bit rate Verdict Acceptable, only with --min acceptable.

Among files with the same worst problem, the worse comes first: more audio lost, an earlier cutoff or a lower bit rate. A file with several problems is counted once, by its worst, and its reasons are all listed.

Clipping, at least 0.1% of the samples in runs at full scale, is named among the reasons of a listed file but never lists a file on its own: a new copy of the same master is clipped too. With --all, a clipped file that is otherwise fine shows under Keep with its clipping in the reason.

Option Effect
--all List every track with its verdict, the files to replace first, then the rest under Keep.
--min <VERDICT> The verdict from which a file is worth replacing: acceptable, weak (the default, weak on a big system) or reencoded. Damaged files are listed whatever it is.
--json Print JSON instead of the list.
--csv <FILE> Also write the list as a CSV file, with the same rows as the list.
--m3u <FILE> Also write the files to replace as an M3U8 playlist, to find them in rekordbox, Serato, Traktor or another DJ program.
--force Replace the CSV or M3U8 file if it exists. Without it, an existing file is an error.

The analysis options of euphoria analyze also apply: --jobs, --audio-budget, --no-cache, --reanalyze, --tempo-range and --key-engine.

The JSON object has schema_version (1), threshold (the --min verdict in kebab case), summary (tracks, to_replace, by_problem with problem, label and count for each problem a file has, and line, the first line of the list) and tracks, in the order of the list. Each track has path, relative_path, artist, title, verdict, verdict_label, to_replace, problems (in kebab case, worst first), reasons (the short reasons of the list), explanation (the sentence euphoria analyze --detail gives), notes and quality, the full report as in euphoria analyze.

The CSV file has the columns Path (relative), Artist, Title, Verdict, To replace (yes or no), Problems, Reason and Full path. The M3U8 playlist is called “Files to replace” and holds only the files to replace, in the order of the list, by their full path.

Files that cannot be read at all are listed on standard error with the reason; they are worth replacing too. The exit status is that of euphoria analyze.

euphoria mashup

Finds tracks that layer over a track, playing at the same time rather than one after the other: the same ideas, in the same order, as mashup mode of the desktop app’s decks. With a second track and --render, it writes the pair to a WAV file the way the decks export it.

euphoria mashup [OPTIONS] <TRACK_A>
euphoria mashup [OPTIONS] <TRACK_A> <TRACK_B> --render <OUT.wav>

Tracks are analyzed first or read from the cache, with your corrections applied. A candidate layers when its key, shifted by up to two semitones, is the same, the relative or an adjacent key, and its tempo is within 8 percent; Mashups explains the ranking. Stems come from the stem cache, filled by euphoria stems or the app; listing never separates a track.

$ euphoria mashup "Low Tide.flac" --limit 2
Layer over Low Tide  8A  124.0 BPM  energy 6
1  8A  Night Drive
   8A is the same key as A
   Same tempo, no stretch
   Vocals of A over the instrumental of B, and B has no vocals of its own; they sit in different ranges (12% overlap)
   Energy 6 = against A
2  10A  Glow
   Shift B down 2 semitones: 10A becomes 8A, the same key as A
   Stretched 1.6% down to A's tempo
   Stems not compared: separate both tracks to check vocals against instruments
   Energy 7 ↑1 against A
Option Effect
--library <DIR> Folders to choose from. May be given more than once. Defaults to the folder of TRACK_A.
--playlist <NAME> A playlist built in the app to choose from, in place of --library.
--key-moves <MOVE> The key moves that count, separated by commas: same, relative, adjacent, diagonal, energy-boost, mood-change and semitone-boost. Defaults to same,relative,adjacent. A shift aims for any move that counts.
--tempo-window <PERCENT> The largest tempo difference B is stretched across. Defaults to 8.
--bpm <RANGE>, --energy <RANGE> Choose only tracks in this tempo or energy range, written as for euphoria analyze.
--genre <TEXT> Choose only tracks whose genre tag contains the text, ignoring case.
--stems <TRACK=PART> What each track plays: a= or b= with full, vocals or instrumental, separated by commas. A side left out takes the other part, so a=vocals plays the instrumental of B. Listing, a part for A ranks first the tracks whose stems go with it.
--limit <COUNT> How many ideas to list. Defaults to 10.
--json Print JSON instead of text.
--key-notation <NOTATION> How keys are written.

The analysis options of euphoria analyze also apply: --jobs, --no-cache, --reanalyze and --tempo-range.

Each idea has the key and name of the track, then one line per reason: the key, with the shift B needs; the stretch; how the stems layer, or that they were not compared; and the energy change. A note on standard error says why a list is empty or short, and when A has no stems.

The JSON object has schema_version (1), track (path, artist, title, genre, key, key_name, bpm, energy and has_stems), part (the part chosen for A, or null) and ideas: one object per idea with rank from 1, the same fields as track, shift_semitones, shifted_key, key_move (as in next), tempo_percent, tempo_scaling (direct, half or double), energy_change, stems and reasons (the sentences). stems is null when either track has no stems, and otherwise has the part of each track in a and b, overlap_percent and muted_vocals (the track whose own vocals are muted, or null).

Render a pair

Option Effect
--render <OUT.wav> Render TRACK_A and TRACK_B together into this file.
--shift <N> Shift B by N semitones, from -6 to 6. Defaults to the shift the ideas suggest for the pair, or none when the keys do not layer.
--stems <TRACK=PART> As above. Without it, the pair plays as its idea does when both tracks have stems, and both whole otherwise. A part other than full for a track without cached stems separates it first.
--force Replace the output file if it exists.

Each track starts at its first downbeat, or at its start without a beat grid. B is stretched to A’s tempo, at half or double when that is closer, and shifted; A plays as it is. The file is 24 bit stereo at 44.1 kHz and lasts until the longer layer ends; when the two would clip together the whole file is turned down to 1 dB below full scale, and a note says by how much. The tracks are only read, and an output that is one of them is refused.

Standard output says where the file is and how long it lasts, then one line per track: the part it plays, its shift, its speed and where it starts. With --json it is an object with schema_version (1), path, seconds, turned_down_db, and a and b, each with the track fields above plus part, shift_semitones, rate and start_seconds.

The exit status is 0 when the list or the file was made, even an empty list, and 1 when a track could not be analyzed, has no tempo for a render, the output exists without --force, does not end in .wav or is one of the tracks.

euphoria tags write

Analyzes audio files and writes the key, tempo and energy into their tags, after showing every change and asking for confirmation. Write tags into your files walks through it, and Tags lists the fields and describes how a file is rewritten.

euphoria tags write [OPTIONS] <PATHS>...

Paths are searched as in euphoria analyze, and results come from the cache when the tracks were analyzed before.

$ euphoria tags write ~/Music/DJ
/Users/you/Music/DJ/low tide.flac
  INITIALKEY: (none) -> 8A
  KEY: (none) -> 8A
  BPM: (none) -> 124.04
  COMMENT: https://example.com/track/42 -> 8A - Energy 7 - https://example.com/track/42
340 files to change, 2 already up to date.
Write these changes to 340 files? [y/N] y
Wrote the tags of 340 files.
hint: To put the old tags back, run `euphoria tags undo`.

Options

Option Effect
--dry-run Show the preview and write nothing. Cannot be combined with --yes.
-y, --yes Write without asking for confirmation. Also needed when rekordbox, Serato DJ, Traktor, Engine DJ or VirtualDJ is running: the command warns that the program may lose the change and writes nothing without --yes.
--key-notation <NOTATION> camelot (the default) writes keys such as 8A, musical writes keys such as Am, open-key writes keys such as 1m. Applies to the key field and to the label.
--no-tempo Leave the tempo field alone.
--tempo Write the tempo with the serato preset, which leaves it out otherwise. Cannot be combined with --no-tempo.
--label <WHERE> Where the key and energy label, such as 8A - Energy 7, goes: comment-start, comment-end, grouping, or none to write no label. The text already in the field is kept. The default is none with the generic preset and comment-start with a DJ program’s preset. Before this changed, comment-start was the default for every preset. When the label is off and files would change, a line hint: the energy is not written. Add --label comment-start to write "8A - Energy 7". says how to turn it on.
--overwrite Replace a key or tempo the file already has. Without it, one that can be read is kept, unless an earlier tags write wrote it and it is unchanged. The preview lists each one kept.
--include-low-confidence Also write a key or tempo rated low confidence. Without it, those are left out and listed. A key or tempo you corrected counts as high confidence.
--preset <PROGRAM> The DJ program whose tag fields are written: generic (the default), rekordbox, serato, traktor, engine-dj, virtualdj or mixxx. See use Euphoria with your DJ program.
--serato-markers Also write each track’s cue points and beat grid where Serato DJ reads them, in MP3, AIFF, M4A and FLAC files, keeping every cue and grid the files already have. The cues you set in the desktop app are written instead of the automatic ones, on their pads. Not tested in Serato. See cue points and beat grids for Serato.
--cue-colors <COLOURS> energy (the default) gives each cue point analysis placed the Serato pad colour nearest to the energy of its section; fixed gives each the colour Serato gives its pad. Your own cues keep their pad colour. Needs --serato-markers.
--tempo-range <SLOWEST-FASTEST> The range tempos are written in, 90-180 by default, as for euphoria analyze.
-j, --jobs <N> Analyze N files at once. The default is the number of cores, at most 8.
--no-cache Analyze every file, and neither read nor update the cache.
--reanalyze Analyze every file again and replace its cached result. Cannot be combined with --no-cache.
-h, --help Show help.

Safe defaults

The defaults of tags write changed so that it never silently damages a tag that is right: an existing readable key or tempo is kept (--overwrite restores the old replacing), a key or tempo rated low confidence is left out (--include-low-confidence restores writing them), the generic preset writes no label (--label comment-start restores it) and a running DJ program needs --yes. Write tags explains each and how Euphoria tells its own earlier values from yours.

Preview and confirmation

The preview goes to standard output: the path of each file that would change, then one line per field with the value it has and the value it would get, then a line for each key or tempo left out, such as key kept (already tagged 8A) or tempo not written (rated low confidence). A file with nothing to change that has such a line is listed too. (none) stands for a field the file does not have. Files that already hold the values are not listed and are never touched. Producing the preview only reads the files.

Standard error then gets one line with the number of files to change, the number already up to date and the number left out because of errors, and the question. Only y or yes writes. With --dry-run there is no question. When there is nothing to change there is no question either.

When standard input is not a terminal and --yes was not given, nobody can answer the question. The command then writes nothing, says so with error: nothing was written and a hint, and exits with status 1. An answer sent through a pipe is not read.

What is written and how

Each file is written as described in Tags: only the fields in the preview change, every other byte of the file is carried over, and the new file is checked against the original before it takes its place. The backup of each file is saved in the tag-writes folder of the data folder before the file is changed.

Exit status

Paths, tag values and error messages come from the files, so before they are shown, characters that could act on the terminal, such as a carriage return, an escape sequence or a text direction override, are replaced by visible escapes such as \r and \u{1b}. A file cannot erase or disguise the preview you are asked to confirm. The same holds for the table of euphoria analyze and the messages of euphoria export. What is written into the tags is the real text. JSON output carries the real text with JSON’s own escapes.

A file that fails does not stop the others. A file that cannot be analyzed, or whose tags cannot be read or written, is listed on standard error as error: <path>: <reason> and left unchanged. That includes the files the tag writer refuses, such as a file with more than one hard link or a file another program changed during the write.

If a file was changed but the log of the write could not note it, for example because the disk filled up, the file is listed as warning: <path>: the file was changed, but the record of it could not be saved. Its backup was saved before the change, so euphoria tags undo still restores it.

The command exits with status 0 when every file was written or was already up to date, and also when you answered no. It exits with status 1 when any file failed, when a change could not be recorded, when it could not ask for confirmation, and, after writing, when saving analysis results to the cache failed partway.

euphoria tags set

Edits tag fields by hand across many files at once: give a field a value, remove it, find and replace in it, or add or remove a prefix or a suffix. It shows the same preview and asks the same question as euphoria tags write, writes the same safe way, and euphoria tags undo puts the old tags back.

euphoria tags set [OPTIONS] <PATHS>...
$ euphoria tags set --field "genre=Deep House" --field year=2024 ~/Music/DJ/new
/Users/you/Music/DJ/new/low tide.flac
  GENRE: House -> Deep House
  DATE: (none) -> 2024
...
14 files to change, 0 already up to date, 0 left out.
Write these changes to 14 files? [y/N]

Nothing is analyzed. The fields are the same in every format:

Field ID3 (MP3, WAV, AIFF) MP4 (M4A, MP4) Vorbis (FLAC, Ogg Vorbis)
title TIT2 ©nam TITLE
artist TPE1 ©ART ARTIST
album TALB ©alb ALBUM
genre TCON ©gen GENRE
year TYER, or TDRC in an ID3v2.4 tag ©day DATE
track TRCK trkn TRACKNUMBER
comment COMM ©cmt COMMENT
grouping TIT1 ©grp GROUPING
key TKEY ----:com.apple.iTunes:initialkey INITIALKEY
bpm TBPM ----:com.apple.iTunes:BPM BPM

tempo, date and tracknumber are accepted for bpm, year and track. When a file also has another field of the same meaning, such as the KEY field of a FLAC or Ogg Vorbis file, the integer tmpo tempo of an M4A file or the GRP1 grouping of an MP3, that field gets the same change, so programs that read either agree. A WAV file’s title, artist, album, genre, date, track number and comment also go into its RIFF INFO list, which rekordbox and others read in place of the ID3 chunk.

A comment or a grouping keeps the key and energy label that tags write put there, such as 8A - Energy 7: the edit changes your own text next to it. --field "comment=Peak opener" turns 8A - Energy 7 - Purchased into 8A - Energy 7 - Peak opener, --clear comment leaves 8A - Energy 7, and a value typed with its label, such as 8A - Energy 7 - Opener, replaces the label rather than adding a second one. Only a label with an energy rating is recognised, so text of yours that starts with a key is kept as it is.

Options

Option Effect
--field <FIELD=VALUE> Give a field a value. An empty value, such as album=, removes the field. May be given more than once.
--clear <FIELD> Remove a field. May be given more than once.
--replace <FIELD> with --find <TEXT> and --with <TEXT> Replace every occurrence of the text in the field. Letters match in either case unless --match-case is given. --with "" deletes the text.
--add-prefix <FIELD=TEXT>, --add-suffix <FIELD=TEXT> Put text in front of or after a field, unless it is already there. A file without the field is left without it.
--remove-prefix <FIELD=TEXT>, --remove-suffix <FIELD=TEXT> Take text off the front or the end of a field, where it is there.
-y, --yes Write without asking.
--dry-run Show the preview and write nothing.
-h, --help Show help.

Several edits of the same field apply in the order of this table. A value that leaves nothing removes the field. A tempo must be a positive number, and a track number a number such as 7 or 7/12; a file whose value would not be one is listed as an error and left unchanged.

The preview, the question, what is written and the exit status are as for euphoria tags write. A file the cache knew stays known after its tags change, so it is not analyzed again.

euphoria tags undo

Puts back the tags that the last euphoria tags write or euphoria tags set replaced, or the last write or edit made in the desktop app.

euphoria tags undo [--dry-run | --list]
Option Effect
--list List the writes that can be undone, newest first, with when each was made (UTC) and how many files it changed. The first is the one the next undo restores. Changes nothing.
--dry-run List the files the next undo would restore and when they were written. Changes nothing. Cannot be combined with --list.
$ euphoria tags undo
/Users/you/Music/DJ/low tide.flac
...
Restored the tags of 340 files.

--list prints one line per write, such as 2026-11-15 14:03 UTC 340 files (the next undo restores this one). --dry-run prints Would restore the tags of 340 files, written 2026-11-15 14:03 UTC. Nothing was changed. and the path of each file. Both exit with status 0, and both say There is no tag write to undo. when there is none. A write that only partly succeeded lists the files it changed.

Each restored file is listed on standard output and is byte for byte what it was before the write. Running the command again undoes the write before that one. When there is nothing to undo it says so and exits with status 0.

A file whose tags changed after the write is not restored, so that the later change is not lost. It is listed on standard error with the reason, the other files are restored, and the command exits with status 1. The backup of such a file is kept, and running the command again tries it again. An earlier write cannot be undone while such a file remains.

A write that was interrupted can be undone as well. Files it had not changed yet are counted in the summary as not changed by the write.

euphoria shift

Writes a copy of a track in another key, with the same tempo. The pitch moves by up to 6 semitones either way while every beat stays where it was. The copy is a 24 bit WAV or FLAC file tagged with the new key, and the original is never changed.

euphoria shift [OPTIONS] -s <N> -o <FILE> <FILE>
$ euphoria shift -s 2 track.flac -o "track (+2).flac"
Shifted up 2 semitones, from 8A A minor to 9A B minor, to /Users/you/Music/track (+2).flac

Options

Option What it does
<FILE> The track to shift. It is only read, never changed.
-s, --semitones <N> How many semitones to move the key, from -6 to 6: 2 moves A minor to B minor, -3 moves it to F# minor. A shift of 0 is an error, since nothing would be written.
-o, --output <FILE> The file to write, ending in .wav or .flac. Required.
--force Replace the output file if it exists.
--key-notation <NOTATION> How the shifted key is written into the copy’s tags: camelot (the default), musical or open-key.
-j, --jobs <N> Analyze N files at once. The default is the number of cores, at most 8.
--no-cache Analyze the track without reading or updating the cache.
--reanalyze Analyze the track again and replace its cached result. Cannot be combined with --no-cache.
--tempo-range <SLOWEST-FASTEST> The range tempos are reported in, 90-180 by default, as for euphoria analyze.

The key of the original comes from the cache when the track was analyzed before, with the key you corrected when there is one.

On success, one line goes to standard error: how far the track moved, its key before and after, and where the copy is. The command exits with status 0 when the file is written. It exits with status 1 with a message on standard error when the shift is 0 semitones, the file is not audio Euphoria reads, the output does not end in .wav or .flac, the output exists without --force, or the analysis fails.

euphoria prepare

Writes copies of tracks at one loudness, under a true-peak ceiling, so a set plays evenly on a club system. The guide says why and what each step does.

euphoria prepare [OPTIONS] <PATH>...
$ euphoria prepare ~/Music/Friday --out ~/Music/Prepared
/Users/you/Music/Friday/low tide.flac
  loudness  -14.2 LUFS, gain +5.2 dB, to -9.0 LUFS
  limiting  1.1 dB, true peak -5.3 dBTP, ceiling -1.0 dBTP
  output    /Users/you/Music/Prepared/low tide (prepared).flac
Prepared 1 of 1

Each path is a file or a folder, searched like euphoria analyze. The copies are 24 bit files in the format of the original (WAV, AIFF or FLAC) with its tags and cover art. A lossy original (MP3, AAC, Ogg) becomes FLAC or WAV and is never written as a lossy file. An original is never changed, and a file that exists is never replaced: a taken name gets a number.

Options

Option What it does
<PATH>... Tracks or folders to prepare.
--loudness <LUFS> The integrated loudness to bring every track to. The default is -9; -14, -11 and -7 are the other usual targets.
--true-peak <DBTP> The true-peak ceiling, -1 by default, from -6 to 0.
--max-limiting <DB> The most the limiter may turn peaks down, 3 by default. A track that would need more gets less gain instead, and the output says gain capped.
--tune Shift tracks measured off A = 440 Hz by 3 cents or more back to concert pitch, with the tempo unchanged. Analyzes each track, or reads its cached analysis.
-o, --out <DIR> Write the copies into this folder, created if needed, instead of next to the originals.
--suffix <TEXT> Added to each name before the extension, (prepared) by default.
--lossy-as <FORMAT> What lossy tracks become: flac (the default) or wav.
--tag-only Write the loudness into the tags of the originals as ReplayGain 2.0 track gain and peak (REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK, in the standard field of each format) and write no copies. The audio is not touched. Cannot be combined with --tune or --out.
--revert <MANIFEST_OR_FOLDER> Undo a run, as below. Takes no paths.
--dry-run Measure and print what would be done, and write nothing.
--json Print a JSON document instead of text.
-j, --jobs <N>, --no-cache, --reanalyze, --tempo-range As for euphoria analyze. They matter only with --tune.

Output

For each track the text output gives the measured loudness, the gain and the loudness it ends at, how many dB of limiting that needs and the true peak it starts from, the tuning change with --tune, any clipped passages, and the file written. A dry run prints the same numbers as the real run, because the real run applies the plan the dry run measured.

With --json the document has settings, a tracks array and the counts prepared, skipped and failed. A track has input, output, status (prepared, dry_run, skipped or failed), error, and the plan: measured_lufs, true_peak_dbtp, sample_peak_db, wanted_gain_db, gain_db, limiting_db, gain_capped, predicted_lufs, tuning_cents, tuning_correction_cents, clipping, output_format, sample_rate, channels and duration_seconds. limiter_reduction_db is the reduction the limiter reached while writing. A silent track is skipped with skipped set to its reason.

Every run that writes records a manifest, euphoria-prepare-<time>.json, in the folder of its copies (or, with --tag-only, of the originals): each source and output with BLAKE3 checksums, the settings, and for a tag-only run the ReplayGain fields the file had before.

The command exits with status 0 when every track is written, and with status 1 when one failed or an argument is not valid.

Reverting a run

euphoria prepare --revert <MANIFEST_OR_FOLDER> removes the files a run wrote and puts back the ReplayGain fields a --tag-only run changed. A folder reverts every manifest in it, newest first. A file is only touched when its checksum is still the one the run recorded; a copy you edited since, or any file the manifest does not name, is kept and listed. The manifest is deleted when everything in it is undone, and keeps the entries that were not. The command exits with status 1 when something was kept. There is no replace-in-place mode, so there are no originals to restore except tags.

euphoria stems

Separates a track into vocals, drums, bass and the rest, with the Demucs htdemucs model, and writes one WAV file per stem. The model, 84 MB, is downloaded the first time. Separation runs on this computer. With --mode advanced a larger model separates the track, more cleanly and about seven times more slowly.

euphoria stems [OPTIONS] -o <DIR> <FILE>
euphoria stems --remove <FILE>
$ euphoria stems track.flac --output stems
Drums   /Users/you/Music/stems/drums.wav
Bass    /Users/you/Music/stems/bass.wav
Other   /Users/you/Music/stems/other.wav
Vocals  /Users/you/Music/stems/vocals.wav

Options

Option What it does
<FILE> The audio file to separate.
-o, --output <DIR> The folder to write the stems to, created when missing. Required, except with --remove.
--force Replace stem files already in the folder.
--mix <MIX> Write one file instead of the four stems: acapella or instrumental, named after the track, into the folder.
--mode <MODE> default, the faster, or advanced, which separates more cleanly and takes about 114 seconds per minute of audio and about 4.5 GB of memory on a recent Mac. Defaults to default.
--remove Delete the cached stems of the track, from both modes, so it is separated again next time. The audio file is not touched. Cannot be combined with the other options.

The stems are written as vocals.wav, drums.wav, bass.wav and other.wav, 16 bit stereo WAV files at 44.1 kHz. Each one is listed on standard output with its path, and standard error gets a note: how long the separation took, or that the stems came from the cache. Separated tracks are cached, so separating the same track again is instant.

With --mix acapella or --mix instrumental, one file is written into the folder instead of the four stems: <file name without extension> (Acapella).wav or <file name without extension> (Instrumental).wav, the same 16 bit stereo WAV files at 44.1 kHz. The acapella is the vocals stem, and the instrumental is the drums, bass and other stems summed in 32 bit floating point; when the sum goes past full scale it is scaled down as a whole so its peak is exactly full scale, and standard error gets a note with the dB it was scaled down by. --force replaces the file when it already exists.

The Advanced mode downloads its model, 214 MB, the first time. Stems it made are used whenever the same track is separated again in either mode; stems made by the default mode are not used by --mode advanced, which separates the track again.

With --remove, standard error says which stems were removed, or that the track had none in the cache; both exit with status 0.

The command exits with status 0 when the stems are written. It exits with status 1 with a message on standard error when the file is not there, a stem file already exists in the folder without --force, an output would replace the input file, or the model download or the separation fails.

euphoria corrections export

Writes every key, tempo and energy you corrected as JSON Lines: one JSON object per line, one line per stored content hash. It is meant for training and evaluating a key, tempo or energy model on the tracks you checked by ear, and it is written on your computer and sent nowhere.

euphoria corrections export [--output <FILE>] [--force] [--include-paths]
$ euphoria corrections export -o corrections.jsonl
Exported 42 corrections to /Users/you/corrections.jsonl
Option Effect
-o, --output <FILE> The file to write. Without it the lines go to standard output and the summary to standard error.
--force Replace the output file if it exists. The source cache and its SQLite companion files cannot be outputs, even with this option.
--include-paths Add the path each file was last seen at.

Nothing is analyzed and no audio file is read: the lines come from the cache, oldest correction first. With no cache, or a cache without corrections, nothing is written to standard output, an output file is empty, and a note says so. A cache that cannot be read is an error, and the command exits with status 1. The file is written in one step, as for euphoria export rekordbox.

What each line holds

By default a line names its track only by the hash of the file’s content: no path and no file name. A program that has the same files finds each one by hashing it the same way. The hash does not hide which track a line is about from someone who has the same file, since they can hash it and look for the result, so treat an export as a list of the tracks you own.

{"schema_version":2,"content_hash":"708c038ada074ff39e9b15496e5116710665a6e916e354e580232fea61674e4e","corrected_key":{"name":"E minor","camelot":"9A","tonic":4,"mode":"minor"},"corrected_bpm":null,"corrected_energy":8,"corrected_at":1794409200,"detected_key":{"name":"A minor","camelot":"8A","tonic":9,"mode":"minor"},"detected_bpm":124.0,"detected_energy":6,"analyzer_version":"12+libkeyfinder","analyzed_at":1794408000}
Field Meaning
schema_version 2. It goes up whenever the fields change; ignore fields you don’t know. Version 2 added corrected_energy and detected_energy; version 1 lines have neither.
content_hash The BLAKE3 hash of every byte of the file, tags and artwork included, as 64 lowercase hexadecimal digits: what b3sum prints for the file.
corrected_key The key you set, or null when you did not correct the key. name is the musical name, camelot the Camelot code, tonic the pitch class of the tonic from 0 (C) to 11 (B), and mode "major" or "minor".
corrected_bpm The tempo you set, as you typed it, or null when you did not correct the tempo.
corrected_energy The energy rating you set, from 1 to 10, or null when you did not correct it.
corrected_at When you set the correction, in seconds since 1 January 1970 UTC.
detected_key The key Euphoria detected for the same content, in the same shape, or null when it found none or the track has no stored analysis.
detected_bpm The tempo Euphoria detected, between 90 and 180 BPM, or null.
detected_energy The energy rating Euphoria detected, from 1 to 10, or null when it rated none or the track has no stored analysis.
analyzer_version The version of the analyzer that detected them, which can be older than the one you run, or null when the track has no stored analysis.
analyzed_at When that analysis was stored, in seconds since 1 January 1970 UTC, or null.
path Only with --include-paths: the absolute path the file was last seen at, or null when the cache never recorded one. The file may have moved since.

A correction follows its file through tag writes. The export includes both its new content hash and older entries retained so a tag write can be undone. One audio track can therefore have several lines for different versions of its tags, and an older hash need not match a file that still exists. A file whose tags another program changed since also has a different hash, and a program matching the export by hash will not find it.

The analysis cache

euphoria analyze and euphoria export remember every result in a SQLite database on your computer, so a track is analyzed once. A later run uses the remembered result instead of analyzing the file again.

A track is recognised by its content, not by its name or folder:

  • A file that was renamed or moved is still recognised, and is not analyzed again.
  • A file whose content changed is analyzed again. Editing tags changes the content, so a file retagged by another program is analyzed once more. euphoria tags write and euphoria tags undo, and the app, record the files they change, so those are not analyzed again; with --no-cache the write records nothing.
  • A file that could not be analyzed is not remembered, and is tried again on the next run.
  • Results from a version of Euphoria that detected keys or tempo differently, or rated energy with a different version of its scale, are ignored and replaced. This includes results stored before Euphoria rated energy, results stored before tempo was reported between 90 and 180 BPM, which changed the tempo of many tracks and the energy rating of some, results stored before the tuning and the key over time were measured, and results stored before keys and tempos were rated for confidence. The first run after such an update analyzes every track once more.
  • A file that changes while it is being analyzed is not remembered, and is analyzed again on the next run.
  • Results stored before the energy of each cue’s section was measured are kept, with no energy on their cues, so updating does not analyze every track again. Those cues keep the pad colours in exports until the track is analyzed again, with --reanalyze or after its file changes.

A file found where it was last seen, with the same size and modification time, is not read at all. Any other file is read once to compute a BLAKE3 hash of its content, which takes a small fraction of the time an analysis does.

Corrections

When you correct a key, a tempo or an energy in the desktop app, the correction is kept in the cache, recognised by the file’s content like an analysis. euphoria analyze shows the corrected value and marks it set by you in the detailed view and in set_by_user, euphoria export rekordbox exports it, and euphoria tags write writes it. With --no-cache, or without a cache, corrections are not read and the detected values are used. To show a correction, a file at its recorded path with its recorded size and modification time is trusted, as for an analysis; before a correction goes into tags or an export, the whole file is read to be sure it is the file that was corrected. When that check fails, because the file cannot be read or the cache cannot be queried, the file is left out of the write or the export and listed with the reason, rather than given the detected values.

Corrections are kept apart from the analyses, so neither --reanalyze, a new version of Euphoria analyzing every track again, nor euphoria cache clear loses them. They follow a file that is moved or renamed, and one whose tags euphoria tags write, euphoria tags undo or the app change. A file whose content is changed by another program is a new file to the cache, and loses its corrections. Resetting a value in the app removes its correction. euphoria corrections export writes them all out, to train a key model on.

Edited cues

When you edit the cues of a track in the desktop app, your set of cues is kept in the cache in the same way, in a table of its own: by the file’s content, apart from the analyses, so --reanalyze, a new version of Euphoria and euphoria cache clear keep it, and it follows a file that is moved, renamed or has its tags written. Your set replaces the cues analysis placed, even when you deleted every cue: euphoria analyze --json lists your cues and "cues" in set_by_user, and euphoria export rekordbox --cues exports them. The loops you save in the app are kept the same way, in a table of their own, listed under loops by euphoria analyze --json, and written by --cues of the rekordbox and Traktor exports and by euphoria tags write --serato-markers. As for corrections, the whole file is read before its cues go into an export, and a file whose edits cannot be checked is left out with the reason. Reset to automatic cues in the app forgets your set. With --no-cache edited cues are not read.

Where the cache is stored

System Location
macOS ~/Library/Application Support/euphoria/analysis-cache.sqlite3
Linux $XDG_DATA_HOME/euphoria/analysis-cache.sqlite3, or ~/.local/share/euphoria/analysis-cache.sqlite3 when XDG_DATA_HOME is not set

Set the EUPHORIA_DATA_DIR environment variable to keep the database in another folder:

EUPHORIA_DATA_DIR=/Volumes/Music/.euphoria euphoria analyze /Volumes/Music

A relative value is taken from the directory the command is run in, so EUPHORIA_DATA_DIR=data run in /Users/you means /Users/you/data. euphoria cache path prints the absolute location that results.

Set EUPHORIA_ASSUME_NO_DJ_PROGRAMS=1 to skip the check for a running DJ program before writing tags or exporting, for scripts and tests on a machine where rekordbox, Serato DJ, Traktor, Engine DJ or VirtualDJ happens to be open. Euphoria then no longer protects a write from a program saving the same file at the same moment, so leave it unset for everyday use.

Several euphoria analyze and euphoria export commands can run at the same time and share one database.

When the cache cannot be used

The cache only saves time, so a problem with it never stops an analysis. If the database cannot be opened or read, for example because the file is damaged, its folder is read only, or it was written by a newer version of Euphoria, euphoria analyze prints a warning on standard error and analyzes every file without the cache:

warning: analyzing without the cache: cannot use the analysis cache at /Users/you/Library/Application Support/euphoria/analysis-cache.sqlite3: file is not a database
hint: Run `euphoria cache clear` to reset the cache, or pass --no-cache to skip it.

The results and the exit status are the same as with --no-cache. Nothing is read from or saved to the cache in that run.

euphoria tags write and euphoria export rekordbox stop instead, before analyzing anything, and write nothing: the cache may hold keys and tempos you corrected and cues you edited, and the detected values must not replace them without your knowing. Pass --no-cache to go on with the detected values, or run euphoria cache clear to reset a damaged cache.

euphoria completions

Prints a script that completes euphoria commands, options and their values in your shell.

euphoria completions <SHELL>

SHELL is bash, zsh, fish or powershell. The script goes to standard output. Install it once:

Shell Install
zsh euphoria completions zsh > ~/.zfunc/_euphoria, with fpath+=~/.zfunc before compinit in ~/.zshrc
bash euphoria completions bash > ~/.local/share/bash-completion/completions/euphoria (needs the bash-completion package)
fish euphoria completions fish > ~/.config/fish/completions/euphoria.fish
PowerShell euphoria completions powershell >> $PROFILE

Open a new shell afterwards. Homebrew installs the bash, zsh and fish scripts with the formula. Playlist names are not completed.

euphoria cache

Manages the analysis cache.

euphoria cache <COMMAND>
Command Effect
path Print the location of the cache database.
clear Forget every cached result. Every track is analyzed again on the next run. Corrections and edited cues are kept.

clear empties the database and keeps the file, so it is safe while an analysis is running: that analysis carries on, and the results it saves after the clear are kept. A database that cannot be opened, such as a damaged file, is deleted instead, and the next run creates a new one. Unlike euphoria analyze and euphoria export, both commands report a problem as an error and exit with status 1.

$ euphoria cache path
/Users/you/Library/Application Support/euphoria/analysis-cache.sqlite3

Messages

Every command writes its results to standard output and everything else to standard error, in one shape:

Starts with Means
error: Something failed: the file, if there is one, then the reason. The exit status is 1.
missing: A file that is no longer there: moved, deleted, or on a drive that is not connected. When nothing else failed, the exit status is 3.
warning: Something went wrong that did not stop the command, such as a cache that could not be used.
hint: What to do next.
note: Something worth knowing that needs no action.

euphoria --help and the help of every command end with examples.

When the program reading standard output stops early, as head does in euphoria plan a.flac b.flac --json | head, the command ends quietly with status 0 rather than reporting a broken pipe.

Colour

Colour is used only for text that goes to a terminal: the key in the hue of its Camelot number, red for errors, yellow for warnings and for ratings worth a look, green for what is fine, bold for what matters and dim for what is secondary. JSON and the plain table never hold colour unless asked.

Setting Effect
--color auto The default. Colour a terminal, unless NO_COLOR is set to any value or CLICOLOR is 0, or colour everything when CLICOLOR_FORCE is set to anything but 0. NO_COLOR wins over CLICOLOR_FORCE.
--color always Colour everything, even into a pipe.
--color never Never colour.

--color can be given before or after the command, and applies to the help as well. Keys use 24 bit colour when COLORTERM is truecolor or 24bit, and the nearest of 256 colours otherwise.

Edit this page on GitHub