FAQ.md:

- check_autocue_setup explained
- First steps with your own script

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)
 <!-- Generated by gh-toc, https://moonbase59.github.io/gh-toc/ -->
 <!-- ToC end -->
 
@@ -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.
+
+
+## <a name="why-should-i-use-check_autocue_setup-and-what-does-it-do"></a>Why should I use `check_autocue_setup`, and what does it do? <a href="#toc" class="goToc">⇧</a>
+
+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
+  ```
+
+## <a name="what-are-good-first-steps-to-include-autocue-in-my-own-liquidsoap-script"></a>What are good first steps to include Autocue in my own Liquidsoap script? <a href="#toc" class="goToc">⇧</a>
+
+- 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!