From db1b78517352f5657ffd353c6c34995d76399621 Mon Sep 17 00:00:00 2001 From: Moonbase59 Date: Mon, 17 Jun 2024 23:14:38 +0200 Subject: [PATCH] Update Presentation --- README.md | 2 +- docs/presentation/autocue.html | 176 +++++++++++------- docs/presentation/autocue.md | 172 ++++++++++------- docs/presentation/autocue.pdf | Bin 5328943 -> 5346120 bytes .../images/AzuraCast Autocue Settings.png | Bin 122935 -> 156778 bytes 5 files changed, 215 insertions(+), 135 deletions(-) diff --git a/README.md b/README.md index 2f3396e..9a2cdec 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Depending on your settings, you’ll get some result files for further study: Since AzuraCast Rolling Release \#caeea9d (2024-05-21), it is _built-in!_ -In your station, just got to _Profile → Edit Profile → AutoDJ → Audio Processing_ and _enable_ it here: +In your station, just go to _Profile → Edit Profile → AutoDJ → Audio Processing_ and _enable_ it here: ![Screenshot of AzuraCast setting Enable Autocue; enabled.](https://github.com/Moonbase59/autocue/assets/3706922/4f8f6055-18f8-4fc7-99c4-0884f301c1d4) diff --git a/docs/presentation/autocue.html b/docs/presentation/autocue.html index 681bad4..1cdb5da 100644 --- a/docs/presentation/autocue.html +++ b/docs/presentation/autocue.html @@ -4,7 +4,7 @@ - + Autocue @@ -46,9 +46,9 @@

Autocue

Liquidshop 4 -Presentation

+Presentation (updated)

Matthias C. Hormann (“Moonbase59”)

-

2024-05-27

+

2024-06-17

@@ -616,63 +624,96 @@

Commandline usage

Use cue_file --help for more information.

$ cue_file --help
-usage: cue_file [-h] [-t TARGET] [-s SILENCE] [-o OVERLAY]
-                [-l LONGTAIL] [-x EXTRA] [-k] [-b] [-w] [-f]
-                [-n]
+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
 
-Return cue-in, cue-out, overlay and replaygain data for an
-audio file as JSON. To be used with my Liquidsoap "autocue:"
-protocol.
+Analyse audio file for cue-in, cue-out, overlay and EBU R128 loudness data,
+results as JSON. Optionally writes tags to original audio file, avoiding
+unnecessary re-analysis and getting results MUCH faster. This software is
+mainly intended for use with my Liquidsoap "autocue:" protocol.
+
+cue_file 4.0.2 supports writing tags to these file types:
+.aac, .aif, .aifc, .aiff, .alac, .ape, .asf, .flac, .m2a, .m4a, .m4b, .m4p,
+.m4r, .m4v, .mp+, .mp2, .mp3, .mp4, .mpc, .ofr, .ofs, .oga, .ogg, .ogv, .opus,
+.spx, .wav, .wma, .wmv, .wv.
+More file types are available when Mutagen is installed (True).
 
 positional arguments:
   file                  File to be processed
 
 options:
   -h, --help            show this help message and exit
+  -V, --version         show program's version number and exit
   -t TARGET, --target TARGET
-                        LUFS reference target (default: -18.0)
+                        LUFS reference target; -23.0 to 0.0 (default: -18.0)
   -s SILENCE, --silence SILENCE
-                        LU below integrated track loudness for
-                        cue-in & cue-out points (silence
-                        removal at beginning & end of a track)
-                        (default: -42.0)
+                        LU below integrated track loudness for cue-in & cue-
+                        out points (silence removal at beginning & end of a
+                        track) (default: -42.0)
   -o OVERLAY, --overlay OVERLAY
-                        LU below integrated track loudness to
-                        trigger next track (default: -8.0)
+                        LU below integrated track loudness to trigger next
+                        track (default: -8.0)
   -l LONGTAIL, --longtail LONGTAIL
-                        More than so many seconds of calculated
-                        overlay duration are considered a long
-                        tail, and will force a recalculation
-                        using --extra, thus keeping long song
+                        More than so many seconds of calculated overlay
+                        duration are considered a long tail, and will force a
+                        recalculation using --extra, thus keeping long song
                         endings intact (default: 15.0)
   -x EXTRA, --extra EXTRA
-                        Extra LU below overlay loudness to
-                        trigger next track for songs with long
-                        tail (default: -15.0)
-  -k, --noclip          Clipping prevention: Lowers track gain
-                        if needed, to avoid peaks going above
-                        -1 dBFS. Uses true peak values of all
-                        audio channels. (default: False)
-  -b, --blankskip       Skip blank (silence) within song (get
-                        rid of "hidden tracks"). Sets the cue-
-                        out point to where the silence begins.
-                        Don't use this with spoken or TTS-
-                        generated text, as it will often cut
-                        the message short. (default: False)
-  -w, --write           Write Liquidsoap liq_* tags to file.
-                        USE WITH CARE, as ffmpeg can't write
-                        all tags to all file types! Ensure you
-                        have enough free space to hold a copy
-                        of the original file. (default: False)
-  -f, --force           Force re-calculation, even if tags
-                        exist (default: False)
-  -n, --nice            Linux/MacOS only: Use nice? Will run
-                        analysis at nice level 18. (default:
+                        Extra LU below overlay loudness to trigger next track
+                        for songs with long tail (default: -15.0)
+  -d DROP, --drop DROP  Max. percent loudness drop at the end to be still
+                        considered having a sustained ending. Such tracks will
+                        be recalculated using --extra, keeping the song ending
+                        intact. Zero (0.0) to switch off. (default: 40.0)
+  -k, --noclip          Clipping prevention: Lowers track gain if needed, to
+                        avoid peaks going above -1 dBFS. Uses true peak values
+                        of all audio channels. (default: False)
+  -b [BLANKSKIP], --blankskip [BLANKSKIP]
+                        Skip blank (silence) within track if longer than
+                        [BLANKSKIP] seconds (get rid of "hidden tracks"). Sets
+                        the cue-out point to where the silence begins. Don't
+                        use this with spoken or TTS-generated text, as it will
+                        often cut the message short. Zero (0.0) to switch off.
+                        Omitting [BLANKSKIP] defaults to 5.0 s. (default: 0.0)
+  -w, --write           Write Liquidsoap liq_* tags to file. Ensure you have
+                        enough free space to hold a copy of the original file.
+                        (default: False)
+  -r, --replaygain      Write ReplayGain tags to file (track only, no album).
+                        Useful if your files have no previous RG tags. Only
+                        valid if -w/--write is also specified. (default:
                         False)
-
-Please report any issues to
-https://github.com/Moonbase59/autocue/issues
+ -f, --force Force re-analysis, even if tags exist (default: False) + -n, --nice Linux/MacOS only: Use nice? Will run analysis at nice + level 18. (default: False) + -j JSON, --json JSON Read/override tags from a JSON file. Use - to read + from stdin. Intended for pre-processing software which + can, for instance, fill in values from their database + here. (default: None) + +Note cue_file will use the LARGER value from the sustained ending and longtail +calculations to set the next track overlay point. This ensures special song +endings are always kept intact in transitions. + +cue_file 4.0.2 knows about these tags: +duration, liq_amplify, liq_amplify_adjustment, liq_blank_skipped, +liq_blankskip, liq_cross_duration, liq_cross_start_next, liq_cue_duration, +liq_cue_in, liq_cue_out, liq_fade_in, liq_fade_out, liq_hook1_in, +liq_hook1_out, liq_hook2_in, liq_hook2_out, liq_hook3_in, liq_hook3_out, +liq_longtail, liq_loudness, liq_loudness_range, liq_ramp1, liq_ramp2, +liq_ramp3, liq_reference_loudness, liq_sustained_ending, liq_true_peak, +liq_true_peak_db, r128_track_gain, replaygain_reference_loudness, +replaygain_track_gain, replaygain_track_peak, replaygain_track_range. + +The absolute minimum set to (possibly) avoid a re-analysis is: +duration, liq_cross_start_next, liq_cue_in, liq_cue_out, +replaygain_track_gain. + +A full audio file analysis can take some time. cue_file tries to avoid a +(re-)analysis if all required data can be read from existing tags in the file. + +Please report any issues to https://github.com/Moonbase59/autocue/issues
@@ -731,13 +772,13 @@

Tag example

ReplayGain Tags

 
ReplayGain tags are used by cue_file
-but never written back to audio files.
+but only written back to audio files on request.
This preserves your data from unintended changes.

Annotation example

uri = "/home/matthias/Musik/Other/Jingles/Short"
-jingles = playlist(prefix='annotate:liq_blankskip=false,'
+jingles = playlist(prefix='annotate:liq_blankskip=0.0,'
   ^ 'liq_fade_in=0.10,liq_fade_out=0.10'
   ^ ':', uri)

A jingles playlist: We want to disable blank skipping and set fade-in @@ -764,8 +805,8 @@

Metadata categories

“Switches”

    -
  • liq_blankskip (bool)
    -Activates/deactivates blank skipping mode
    • +
  • liq_blankskip (float)
    +Sets blank skipping min. duration (0.0=disable)
  • liq_cue_file (bool)
    Enables/disables autocue (i.e., for large video files)
    • @@ -797,6 +838,7 @@

    Informational

  • liq_blank_skipped (bool)
  • liq_cue_duration (s)
  • liq_longtail (bool)
    • +
  • liq_sustained_ending (bool)
  • liq_loudness (LUFS)
  • liq_loudness_range (LU)
  • liq_true_peak (dBFS)
    • @@ -843,8 +885,6 @@

    Download, Documentation

    GitHub repo:
    https://github.com/Moonbase59/autocue/

    -

    Currently (May 2024) please use the files from the -integrate-with-liquidsoap branch!

Docs & Examples on GitHub

@@ -865,9 +905,9 @@

Docs & Examples on GitHub

Roadmap

    -
  • Scrap autocue2. autocue.cue_file is the -supported integrated solution for LS 2.2.5 & newer.
    • -
  • Update documentation.
    • +
  • Scrap autocue2. autocue.cue_file is +the supported integrated solution for LS 2.2.5 & newer.
    • +
  • Update documentation.
  • Fix “double autocue” issue.
  • Fix “new fade-in > old fade-out” issue with toots.
    • @@ -900,7 +940,7 @@

    Links