v4.1.0

CHANGELOG.md

@@ -1,12 +1,25 @@
 # autocue changelog
 
+### 2024-07-05 – v4.1.0
+
+#### New features
+
+- New `liq_cue_file` handling, allows to ignore overrides for `cue_file` data if true. This is mainly for fast-changing files like news or time, for which LS/AzuraCast might not yet have updated the metadata.
+  - _not set_ — default behaviour (metadata can override `cue_file` results)
+  - `false` — don’t autocue (still use metadata if present)
+  - `true` — `cue_file` results override metadata (special use cases)
+
+For a more thorough explanation, see the [FAQ](FAQ.md#what-exactly-is-liq_cue_file-for-and-should-i-use-it)
+
+
 ### 2024-07-04 – v4.0.6
 
 - Make `duration` non-overridable by existing metadata or annotations.
   - The real file duration is not a tag, but determined otherwise.
   - If such a tag is found, it is typically unusable, incorrect or in a different format.
   - AzuraCast might annotate the duration from an earlier version of the file, because the media scan is only done once in a while. With frequently changing files of the same name, like syndicated news or time announcements, this could be problematic.
 
+
 ### 2024-07-02 – v4.0.5
 
 - Fixed a situation where `cue_file` would read a string duration from ffprobe for audio stream \#0, which led to an error in the AzuraCast log like this:

FAQ.md

@@ -1,5 +1,5 @@
 ---
-date: 2024-07-01
+date: 2024-07-05
 author: Matthias C. Hormann (Moonbase59)
 ---
 # FAQ – Frequently Asked Questions
@@ -27,6 +27,7 @@ author: Matthias C. Hormann (Moonbase59)
 - [What are good first steps to use Autocue in my own Liquidsoap script?](#what-are-good-first-steps-to-use-autocue-in-my-own-liquidsoap-script)
 - [What will happen when I switch to the upcoming Liquidsoap 2.3.0?](#what-will-happen-when-i-switch-to-the-upcoming-liquidsoap-230)
 - [What can I do if some files or a remote playlist simply _don’t play?_](#what-can-i-do-if-some-files-or-a-remote-playlist-simply-dont-play)
+- [What exactly is `liq_cue_file` for, and should I use it?](#what-exactly-is-liq_cue_file-for-and-should-i-use-it)
 <!-- Generated by gh-toc, https://moonbase59.github.io/gh-toc/ -->
 <!-- ToC end -->
 
@@ -386,3 +387,40 @@ _Save Changes_ and _Restart Broadcasting_.
 Keep watching your logs for timeouts, just in case even larger files arrive. You can search for `Time limit exceeded` to quickly find such entries in the log.
 
 If the above should _not_ help, you should look for a _faster/higher bandwidth connection_ to the source you download the files from. To be able to _work_ with a file, Liquidsoap has to download a complete copy first, before autocueing and playout can begin.
+
+
+## <a name="what-exactly-is-liq_cue_file-for-and-should-i-use-it"></a>What exactly is `liq_cue_file` for, and should I use it? <a href="#toc" class="goToc">⇧</a>
+
+Starting with v4.1.0, we have a new `liq_cue_file` handling, which allows to ignore overrides for `cue_file` data if true. This is mainly for fast-changing files like news or time, for which LS/AzuraCast might not yet have updated the metadata.
+
+- _not set_ — default behaviour (metadata can override `cue_file` results)
+- `false` — don’t autocue (still use metadata if present)
+- `true` — `cue_file` results override metadata (special use cases)
+
+### What does that mean for me?
+
+AzuraCast and other third-party apps can store (cache) `cue_file` metadata in order to speed up processing. They can also decide to _override_ certain `cue_file` results like _cue_, _fading_ and _ramp_ points, as is done in AzuraCast’s _Visucal Cue Editor_ (VCE) and Advanced track edit tab.
+
+#### Normal operation
+
+For normal operation, just make sure the _tag_ `liq_cue_file` is _not_ set, and you don’t _annotate_ it. Your radio automation will then be able to use whatever Autocue has calculated, and—if needed—be able to _override results_, for instance in AzuraCast’s VCE/Advanced tab.
+
+#### Fast-changing news, time announcements, etc.
+
+Now if you aggregate syndicated news, spoken time announcements or the like _outside_ the app, and use _the same filename_, the app might not immediately know about the change and update its stored metadata, resulting in _wrong_ metadata on playout, even when you carefully pre-tagged the file with `cue_file` in your external process. For instance, AzuraCast’s _media checker_ runs only about every five minutes or so. If you download a syndicated news file at 9:59 and prepare it at 9:59:45, to be played at 10:00 sharp, chances are good the media checker hasn’t yet hit in and updated the metadata. Result: Problems.
+
+If you now _pre-tag_ such a file in your external process, using the `liq_cue_file` tag and set it to `true`, the Autocue in Liquidsoap will know you want to use the _tagged_ `cue_file` results and _ignore_ the values it might have gotten from elsewhere (stored, annotated, etc.).
+
+A corresponding _log entry_ will be made by Autocue in this case:
+
+```
+[autocue.cue_file:3] cue_file results override existing metadata because liq_cue_file=true tells us to.
+```
+
+#### Large video files and others you don’t want to autocue
+
+Autocue is a CPU-intensive process. So if your station plays large video files, for instance, you will want to _exclude_ these from being autocued. Do this by _tagging_ or _annotating_ the file or playlist using `liq_cue_file` and set it to `false`. Even if Autocue is enabled by default, it will then know to skip these files and write a log entry to that effect:
+
+```
+[autocue.cue_file:2] Skipping cue_file for "filename" because liq_cue_file=false forbids it.
+```

README.md

@@ -47,7 +47,7 @@ Both standalone Liquidsoap operation and integrated playout systems like AzuraCa
     - [Minimal working example](#minimal-working-example)
     - [Next track and short jingle handling](#next-track-and-short-jingle-handling)
     - [Tags/Annotations that influence `autocue`’s behaviour](#tagsannotations-that-influence-autocues-behaviour)
-      - [`liq_cue_file` (`true`/`false`)](#liq_cue_file-truefalse)
+      - [`liq_cue_file` (`true`/`false`/not set)](#liq_cue_file-truefalsenot-set)
       - [`liq_blankskip` (seconds; 0.0 to disable)](#liq_blankskip-seconds-00-to-disable)
       - [AzuraCast: `jingle_mode` (`"true"`)](#azuracast-jingle_mode-true)
       - [SAM Broadcaster Smart Categories](#sam-broadcaster-smart-categories)
@@ -478,7 +478,11 @@ If you have a long cross duration and a jingle following that is _shorter_ than
 
 There are three possible _annotations_ (or tags from a file) that can influence `autocue`’s behaviour. In an annotation string, these must occur _to the right_ of the protcol, i.e. `autocue:annotate:...` to work as intended. Think of these as "switches" to enable or disable features.
 
-#### <a name="liq_cue_file-truefalse"></a>`liq_cue_file` (`true`/`false`) <a href="#toc" class="goToc">⇧</a>
+#### <a name="liq_cue_file-truefalsenot-set"></a>`liq_cue_file` (`true`/`false`/not set) <a href="#toc" class="goToc">⇧</a>
+
+- _not set_ — default behaviour (metadata can override `cue_file` results)
+- `false` — don’t autocue (still use metadata if present)
+- `true` — `cue_file` results override metadata (special use cases)
 
 You can _disable_ autocueing for selected sources, like maybe a playlist of large video files, even when `autocue` is globally enabled.
 
@@ -502,6 +506,8 @@ If a track has been skipped, it will be shown in the logs like this:
 
 **Note:** Using this makes only sense if you used `enable_autocue_metadata()`. When using the `autocue:` _protocol_ in your annotations, you’d simply leave the `autocue:` part off the annotation instead.
 
+For a more thorough explanation, see the [FAQ](FAQ.md#what-exactly-is-liq_cue_file-for-and-should-i-use-it)
+
 #### <a name="liq_blankskip-seconds-00-to-disable"></a>`liq_blankskip` (seconds; 0.0 to disable) <a href="#toc" class="goToc">⇧</a>
 
 You can _override_ the "blankskip" behaviour (early cue-out of a song when silence is detected) on a per-request or per-playlist basis using a special `liq_blankskip` annotation. This is an "ultimate override" which overrides both `settings.autocue.cue_file.blankskip` and `jingle_mode`.

autocue.cue_file.liq

@@ -41,6 +41,14 @@
 # 2024-07-02 - Moonbase59 - v4.0.5 - Sync with cue_file version
 # 2024-07-04 - Moonbase59 - v4.0.6 - Make duration non-overridable, i.e.,
 #                           it’s ALWAYS taken from the cue_file result.
+# 2024-07-05 - Moonbase59 - v4.1.0 - New `liq_cue_file handling, allows to
+#                           ignore overrides for cue_file data if true. This is
+#                           mainly for fast-changing files like news or time,
+#                           for which LS/AzuraCast might not yet have updated
+#                           the metadata.
+#                           - not set = default (metadata can override cue_file)
+#                           - false = don’t autocue (still use metadata if present)
+#                           - true = cue_file results override metadata
 
 # Lots of debugging output for AzuraCast in this, will be removed eventually.
 
@@ -54,7 +62,7 @@ let settings.autocue.cue_file.version =
   settings.make(
     description=
       "Software version of autocue.cue_file. Should coincide with `cue_file`.",
-    "4.0.6"
+    "4.1.0"
   )
 
 # Internal only! Not a user setting.
@@ -637,24 +645,52 @@ def cue_file(~request_metadata, ~file_metadata, filename) =
         ]
       )
 
-      # only use calculated values if not already annotated in AzuraCast
-      # so we don't overwrite manually set values in the database,
-      # except for non-overridable values like `duration`, which are
-      # ALWAYS taken from the cue_file result.
-      result := list.fold(
-        fun(res, entry) ->
-          if list.assoc.mem(fst(entry), res) then
-            if list.mem(fst(entry), settings.autocue.cue_file.ignored_overrides()) then
-              [...list.assoc.remove(fst(entry), res), entry]  # take cue_file result
+      # `liq_cue_file` determines what happens now:
+      #   tag absent - normal handling, existing metadata preferred
+      #   false - we'll never arrive here (don’t process, use existing metadata)
+      #   true - cue_file metadata preferred (for news, time, etc.)
+
+      if meta["liq_cue_file"] == "" then
+        # no `liq_cue_file`, existing metadata preferred
+        log(
+          level=4,
+          label=label,
+          'Existing metadata can override cue_file results \
+           (default; no liq_cue_file seen).'
+        )
+        result := list.fold(
+          fun(res, entry) ->
+            if list.assoc.mem(fst(entry), res) then
+              if list.mem(fst(entry), settings.autocue.cue_file.ignored_overrides()) then
+                [...list.assoc.remove(fst(entry), res), entry]  # take cue_file result
+              else
+                res  # take existing metadata (meta)
+              end
             else
-              res  # take existing metadata
-            end
-          else
-            [...res, entry]  # append new metadata
-          end,
+              [...res, entry]  # append new metadata (cue_file)
+            end,
           m(),
           result()
-      )
+        )
+      elsif meta["liq_cue_file"] == "true" then
+        # `liq_cue_file=true`, cue_file metadata preferred
+        log(
+          level=3,
+          label=label,
+          'cue_file results override existing metadata \
+           because liq_cue_file=true tells us to.'
+        )
+        result := list.fold(
+          fun(res, entry) ->
+            if list.assoc.mem(fst(entry), res) then
+              res  # take existing metadata (cue_file)
+            else
+              [...res, entry]  # append new metadata (meta)
+            end,
+          result(),
+          m()
+        )
+      end
 
       # make a suffixed string a float
       def make_float(s) =

cue_file

@@ -65,13 +65,16 @@
 #                       - only write known tags, not all `liq_*`
 # 2024-07-02 Moonbase59 - v4.0.5 Fix minor bugs with file duration
 # 2024-07-04 Moonbase59 - v4.0.6 Sync version with autocue.cue_file.liq
+# 2024-07-05 Moonbase59 - v4.1.0 Add `liq_cue_file` to known tags, so we can
+#                         forbid external processes to call us again and
+#                         possibly deliver outdated metadata to us.
 #
 # Originally based on an idea and some code by John Warburton (@Warblefly):
 #   https://github.com/Warblefly/TrackBoundaries
 # Some collaborative work with RM-FM (@RM-FM): Sustained ending analysis.
 
 __author__ = 'Matthias C. Hormann'
-__version__ = '4.0.6'
+__version__ = '4.1.0'
 
 import os
 import sys
@@ -214,6 +217,7 @@ tags_to_check = {
     "liq_cross_duration": float,
     "liq_cross_start_next": float,
     "liq_cue_duration": float,
+    "liq_cue_file": is_true,
     "liq_cue_in": float,
     "liq_cue_out": float,
     "liq_fade_in": float,