diff --git a/FAQ.md b/FAQ.md index 423e6c8..cd8ae2e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -22,6 +22,8 @@ author: Matthias C. Hormann (Moonbase59) - [Can I completely _disable_ the "longtail" feature?](#can-i-completely-disable-the-longtail-feature) - [How to ensure Autocue doesn’t mess with Ad Insertion files?](#how-to-ensure-autocue-doesnt-mess-with-ad-insertion-files) - [How to ensure Autocue doesn’t try to process video files?](#how-to-ensure-autocue-doesnt-try-to-process-video-files) +- [Why should I use `check_autocue_setup`, and what does it do?](#why-should-i-use-check_autocue_setup-and-what-does-it-do) +- [What are good first steps to include Autocue into my own Liquidsoap script?](#what-are-good-first-steps-to-include-autocue-in-my-own-liquidsoap-script) @@ -229,3 +231,61 @@ You can set or annotate the special tag `liq_cue_file` and set it to `false`, wh |liq_cue_file|false| - This will probably only work for `.mp4` type videos right now. Mutagen doesn’t yet support the Matroska (`.mkv`) and WebM (`.webm`) EBML data structure. + + +## Why should I use `check_autocue_setup`, and what does it do?  + +It’s a little check to ensure things for `autocue.cue_file` have been set up correctly, and a good diagnostic, since it logs the versions of your `autocue.cue_file.liq` and external `cue_file` to the log (and console if you set `print=true`). It is important that the Liquidsoap script and the external `cue_file` are the same version, and `autocue.cue_file` integrated properly, otherwise odd things could happen, or Liquidsoap could fall back to its _internal autocue_, and you wouldn’t get the results you expect. + +So _always_ use it, _after_ your settings and _before_ a possible `enable_autocue_metadata()`. (AzuraCast does this automatically for you, so nothing to add in any input box.) + +`check_autocue_setup` will… + +- check if your `autocue.cue_file.liq` and external `cue_file` versions match and log the result for easier debugging: + ``` + 2024/06/21 06:46:51 [autocue.cue_file:2] You are using autocue.cue_file version 4.0.3. + 2024/06/21 06:46:51 [autocue.cue_file:2] The external "cue_file" is version 4.0.3 + ``` +- set its metadata priority: `settings.autocue.metadata.priority := 10` +- set the preferred autocue implementation: `settings.autocue.preferred := "cue_file"` +- set the correct "amplify behaviour": `settings.autocue.amplify_behavior := "keep"` +- set the default cross duration to your specified fade-out duration: `settings.autocue.target_cross_duration := settings.autocue.cue_file.fade_out()`. This is done to avoid problems when your default fade-out is different from Liquidsoap’s default cross duration of `3.0` seconds. The result is logged: + ``` + 2024/06/21 06:46:51 [autocue.cue_file:2] Setting `settings.autocue.target_cross_duration` to 2.5 s, from `settings.autocue.cue_file.fade_out`. + ``` +- If you set `print=true`, the results will also be shown on the console. This is practical when programming, so you don’t have to find the log and look it up. +- If you set `shutdown=true`, your Liquidsoap script will shut down if an error occurs. Most of the time, _you should set this_, because the results are unspecified or you can get a lot of errors if the versions of `autocue.cue_file.liq` and `cue_file` don’t match. +- The log/console output in case of an error looks like this: + ``` + ERROR: autocue.cue_file v4.0.3 doesn’t match external "cue_file" v4.0.2! + Autocue NOT ACTIVATED! + Shutting down... + ``` + +`check_autocue_setup` can be used in two ways: + +- **Automatic:** Handles everything for you, including Liquidsoap shutdown: + ``` + ignore(check_autocue_setup(shutdown=true, print=true)) + ``` +- **Manual:** You want to do some special processing, depending on its result: + ``` + if check_autocue_setup(shutdown=false, print=false) then + # all okay, your code here + else + # error ocurred, your code here + end + ``` + +## What are good first steps to include Autocue in my own Liquidsoap script?  + +- Install Liquidsoap and [Autocue](README.md#install), obviously. +- _Start simple, use the defaults._ It should _work_ first, _then_ you can fine-tune it. +- A good example is in [minimal_example_autocue.cue_file.liq](minimal_example_autocue.cue_file.liq). It shows the basic structure: + - `%include "autocue.cue_file.liq"` + - Do your settings. You can copy _all_ settings [from the README](README.md#settings), and only un-comment those you need. The advantage is: You have them all together and don’t have to look them up every time. + - `ignore(check_autocue_setup(shutdown=true, print=true))` + - `enable_autocue_metadata()` if you want to use it. + - Rest of your script. + +Have fun!