<a name="autocue"></a>autocue <a href="#toc" class="goToc">⇧</a>

If you like what you got, please consider to . Thank you! ❤️

On-the-fly JSON song cue-in, cue-out, overlay, replaygain calculation for Liquidsoap, AzuraCast and other AutoDJ software.

Check out the presentation for an introduction, the FAQ – Frequently Asked Questions, and the changelog for latest information!

[!IMPORTANT] Please read IMPORTANT.md, an update on my personal situation and this project.

[!WARNING] Autocue was made for Liquidsoap 2.2.5 and is not yet fully compatible with the new Liquidsoap 2.3.x rolling release, since some parameters have changed in Liquidsoap. I’ll start working on a new version when back.

Note: This documentation describes the standalone cue_file and autocue.cue_file, my integration into Liquidsoap’s autocue: protocol.

Note: The previous integrate-with-liquidsoap branch is now gone. I updated the master branch and you can get the latest versions from that.

Requires Python3 and ffmpeg with the ebur128 filter. Mutagen highly recommended. (The AzuraCast Docker already has these.)

Tested on Linux and Mac, with several ffmpeg versions ranging from 4.4.2–6.1.1, and running on several stations since a few weeks.

Basically, autocue consists of two parts:

• cue_file, a Python3 script, that returns JSON cueing, loudness and overlay data for an audio file. This can be used standalone, as part of some pre-processing or AutoDJ software, or in conjunction with below.
• The Liquidsoap autocue.cue_file integration, for use with Liquidsoap’s autocue: protocol, which in turn can be used standalone or as part of a larger playout system like AzuraCast or others.

Both standalone Liquidsoap operation and integrated playout systems like AzuraCast (and others) are supported. cue_file, the central part of autocue.cue_file, is available as CLI executable and can be used to integrate into other applications, for example to get the autocue results into a database, or pre-tag your audio files.

<a name="table-of-contents"></a>Table of Contents <a href="#toc" class="goToc">⇧</a>

<!-- ToC begin -->

<a name="toc"></a>

• autocue
  • Table of Contents
  • Install
    • Install cue_file
    • Install Mutagen
    • Local testing with Liquidsoap
    • Install on AzuraCast
      • Settings
  • Command-line interface
  • Parameters and settings reference
  • Tags and metadata reference
    • Categories
    • Tags and metadata used by Autocue
    • Tags and metadata format rules
  • Examples
    • Hidden track
    • Long tail handling
      • Cue-out point
      • Cross duration (where the next track could start and be overlaid)
      • A long tail!
      • Avoiding too much overlap
    • Blank (silence) detection
  • Liquidsoap protocol
    • Minimal working example
    • Next track and short jingle handling
    • Tags/Annotations that influence autocue’s behaviour
      • liq_cue_file (true/false/not set)
      • liq_blankskip (seconds; 0.0 to disable)
      • AzuraCast: jingle_mode ("true")
      • SAM Broadcaster Smart Categories
    • Effect of settings.autocue.cue_file.unify_loudness_correction (true/false)
      • ReplayGain inserted
      • ReplayGain overriding liq_amplify
    • AzuraCast Notes
      • Custom crossfading

<!-- Generated by gh-toc, https://moonbase59.github.io/gh-toc/ --> <!-- ToC end -->

<a name="install"></a>Install <a href="#toc" class="goToc">⇧</a>

<a name="install-cue_file"></a>Install cue_file <a href="#toc" class="goToc">⇧</a>

Put cue_file in your path locally (i.e., into ~/bin, ~/.local/bin or /usr/local/bin) and chmod +x it (make executable).

If you wish, you can now play around with it a bit (use cue_file --help for help), or follow our examples below and analyze some of your audio files. Audacity and spec can be helpful in checking.

<a name="install-mutagen"></a>Install Mutagen <a href="#toc" class="goToc">⇧</a>

Refer to the Mutagen Docs.

When installed, check cue_file --help. It should tell you the file types it can handle, and if Mutagen is installed.

You can use cue_file --version to find out the version of cue_file and Mutagen, if it is installed.

$ cue_file --version
cue_file 4.0.3
mutagen 1.47.0

<a name="local-testing-with-liquidsoap"></a>Local testing with Liquidsoap <a href="#toc" class="goToc">⇧</a>

Use the code in test_autocue.cue_file.liq for some local testing, if you have Liquidsoap installed on your machine.

Adjust the settings near the beginning of the file, then look for

# --- Use YOUR (playlist/single) here! ---

and put in your song and jingle playlist, and possibly a single for testing.

Then run

$ liquidsoap test_autocue.cue_file.liq

Depending on your settings, you’ll get some result files for further study:

• test_autocue.cue_file.log — Log file, use tail -f test_autocue.cue_file.log in another terminal to follow
• test_autocue.cue_file.mp3 — an MP3 recording, to see how well the track transitions worked out
• test_autocue.cue_file.cue — a .cue file to go with the MP3 recording, for finding tracks easier (open this in your audio player)

<a name="install-on-azuracast"></a>Install on AzuraCast <a href="#toc" class="goToc">⇧</a>

Since AzuraCast Rolling Release #caeea9d (2024-05-21), it is built-in!

In your station, just go to Profile → Edit Profile → AutoDJ → Audio Processing and enable it here:

I also recommend to disable Always Write Playlists to Liquidsoap under Advanced Configuration:

This will automatically install cue_file, mutagen and autocue.cue_file.liq into AzuraCast, and change your Liquidsoap configuration as needed.

<a name="settings"></a>Settings <a href="#toc" class="goToc">⇧</a>

You can then add your personal settings in the second input box under Broadcasting → Edit Liquidsoap Configuration.

Here is a little hint: Just copy all possible settings into this input field, commented out, and just un-comment those you want to change. That’s a good way to never forget which settings are possible.

Here is a complete list you can copy, showing the default settings:

# settings.autocue.cue_file.path := "cue_file"
# settings.autocue.cue_file.fade_in := 0.1  # seconds
# settings.autocue.cue_file.fade_out := 2.5  # seconds
# settings.autocue.cue_file.timeout := 60.0  # seconds
# settings.autocue.cue_file.target := -18.0  # LUFS
# settings.autocue.cue_file.silence := -42.0  # LU below track loudness
# settings.autocue.cue_file.overlay := -8.0  # LU below track loudness
# settings.autocue.cue_file.longtail := 15.0  # seconds
# settings.autocue.cue_file.overlay_longtail := -12.0  # extra LU
# settings.autocue.cue_file.sustained_loudness_drop := 40.0  # max. percent drop to be considered sustained
# settings.autocue.cue_file.noclip := false  # clipping prevention like loudgain's `-k`
# settings.autocue.cue_file.blankskip := 0.0  # skip silence in tracks
# settings.autocue.cue_file.unify_loudness_correction := true  # unify `replaygain_track_gain` & `liq_amplify`
# settings.autocue.cue_file.write_tags := false  # write liq_* tags back to file
# settings.autocue.cue_file.write_replaygain := false  # write ReplayGain tags back to file
# settings.autocue.cue_file.force_analysis := false  # force re-analysis even if tags found
# settings.autocue.cue_file.nice := false  # Linux/MacOS only: Use NI=18 for analysis
# settings.autocue.cue_file.use_json_metadata := true  # pass metadata to `cue_file` as JSON

Then Save Changes and Restart Broadcasting.

<a name="command-line-interface"></a>Command-line interface <a href="#toc" class="goToc">⇧</a>

usage: cue_file [-h] [-V] [-t TARGET] [-s SILENCE] [-o OVERLAY] [-l LONGTAIL]
                [-x EXTRA] [-d DROP] [-k] [-b [BLANKSKIP]] [-w] [-r] [-f] [-n]
                [-j JSON]
                file

Analyse audio file for cue-in, cue-out, overlay and EBU R128 loudness data,
results as JSON. Optionally writes tags to original audio