From 421aad73f234cf6ee3d6a59bc95d5d541304fc5d Mon Sep 17 00:00:00 2001 From: Simon Ziegler Date: Thu, 24 Oct 2024 11:26:00 +0200 Subject: [PATCH] Added setup-documentation for config-file and casparcg --- README.md | 6 +- docs/_config.yml | 17 +++ docs/_setup/CasparCG.md | 7 -- docs/_setup/Config.md | 8 -- docs/_setup/JohnCG.md | 7 -- docs/_setup/casparcg.md | 39 ++++++ docs/_setup/johncg.md | 11 ++ docs/_setup/{Client.md => johncg/client.md} | 1 + docs/_setup/johncg/config.md | 132 ++++++++++++++++++++ docs/_usage/client.md | 6 + docs/_usage/elements/Bible.md | 6 +- docs/casparcg.md | 59 +++++++++ docs/index.md | 35 +----- docs/requirements.md | 1 + 14 files changed, 279 insertions(+), 56 deletions(-) delete mode 100644 docs/_setup/CasparCG.md delete mode 100644 docs/_setup/Config.md delete mode 100644 docs/_setup/JohnCG.md create mode 100644 docs/_setup/casparcg.md create mode 100644 docs/_setup/johncg.md rename docs/_setup/{Client.md => johncg/client.md} (97%) create mode 100644 docs/_setup/johncg/config.md create mode 100644 docs/_usage/client.md create mode 100644 docs/casparcg.md diff --git a/README.md b/README.md index 293a842..03ac342 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,9 @@ Generate graphics with song-lyrics or for other church-service-elements and play - countdown: "Add Countdown" button is not working - countdown: some modes don't work as they should - add english bible-file +- stageview: ignore visibility and update docs +- change build-name to not include the build-number +- add documentation for jcg and psm files ## Planned - reenable eslint vue-indent @@ -38,4 +41,5 @@ Generate graphics with song-lyrics or for other church-service-elements and play - move backend to go - use http-status-codes in answer to client - seperate manual and documentation -- test windows 11 and update docs \ No newline at end of file +- test windows 11 and update docs +- make template layer optional too and adjust docs accordingly \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index abac681..7b6f1ef 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -18,6 +18,23 @@ collections: files_and_protocol: output: true +callouts: + warning: + title: Warning + color: red + attention: + title: Attention + color: yellow + important: + title: Important + color: purple + info: + title: Info + color: blue + tip: + title: Tip + color: green + just_the_docs: collections: setup: diff --git a/docs/_setup/CasparCG.md b/docs/_setup/CasparCG.md deleted file mode 100644 index 05bdbc9..0000000 --- a/docs/_setup/CasparCG.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: CasparCG-Setup -layout: page ---- -# CasparCG-Setup - -foobar \ No newline at end of file diff --git a/docs/_setup/Config.md b/docs/_setup/Config.md deleted file mode 100644 index 1f56533..0000000 --- a/docs/_setup/Config.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Config file -layout: page -parent: JohnCG-Setup ---- -# Config file - -foobar \ No newline at end of file diff --git a/docs/_setup/JohnCG.md b/docs/_setup/JohnCG.md deleted file mode 100644 index d400758..0000000 --- a/docs/_setup/JohnCG.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: JohnCG-Setup -layout: page ---- -# JohnCG-Setup - -foobar \ No newline at end of file diff --git a/docs/_setup/casparcg.md b/docs/_setup/casparcg.md new file mode 100644 index 0000000..bdca677 --- /dev/null +++ b/docs/_setup/casparcg.md @@ -0,0 +1,39 @@ +--- +title: CasparCG-Setup +layout: page +nav_order: 2 +--- +# CasparCG-Setup + +For the easiest setup download CasparCG server from their [GitHub](https://github.com/casparcg/server/releases/) and unpack the content into `JohnCG/casparcg`. + +JohnCG can autostart CasparCG (see [config]({% link _setup/johncg/config.md %}) for more details). +For this basic setup, just remove the `# ` infront of `# path`: +```diff +- # path: casparcg_2.4.0 # optional - path to CasparCG-directory to auto-start at launch ++ path: casparcg_2.4.0 # optional - path to CasparCG-directory to auto-start at launch +``` + +CasparCG can be configured through `casparcg.config` - the individual components are documented at the bottom of the config-file. + +A more detailed documentation can be found at [CasparCG]({% link casparcg.md %}) or at the [CasparCG wiki](https://github.com/CasparCG/help/wiki). +The most important ones are: + +## Channels +Multiple channels can be used for multiple individual outputs of JohnCG - for example with different resolutions or as a stage-view. + +A simple configuration with a single output-channel in HD and 25 frames per second outputting to a borderless window. + +```xml + + + 1080p2500 + + + true + true + + + + +``` \ No newline at end of file diff --git a/docs/_setup/johncg.md b/docs/_setup/johncg.md new file mode 100644 index 0000000..7cc0ef8 --- /dev/null +++ b/docs/_setup/johncg.md @@ -0,0 +1,11 @@ +--- +title: JohnCG-Setup +layout: page +nav_order: 1 +--- +# JohnCG-Setup + +{: .important } +On the first startup in windows, the windows firewall will ask multiple times for network communication permission. +This is required for CasparCG to be controlled over or output to the network and JohnCG to be controlled from the network. +This can be changed after the fact in the windows firewall settings. diff --git a/docs/_setup/Client.md b/docs/_setup/johncg/client.md similarity index 97% rename from docs/_setup/Client.md rename to docs/_setup/johncg/client.md index fffff11..1c453ec 100644 --- a/docs/_setup/Client.md +++ b/docs/_setup/johncg/client.md @@ -2,6 +2,7 @@ title: Client layout: page parent: JohnCG-Setup +nav_order: 2 --- # Client You can access the client interface from any modern web browser within the same network by navigating to the server's IP address on port `:8888` (can be changed in config). diff --git a/docs/_setup/johncg/config.md b/docs/_setup/johncg/config.md new file mode 100644 index 0000000..6ece215 --- /dev/null +++ b/docs/_setup/johncg/config.md @@ -0,0 +1,132 @@ +--- +title: Config file +layout: page +parent: JohnCG-Setup +nav_order: 1 +--- +# Config file + +Almost all settings are set in `config.yaml`. + +## `log_level` Logging-level +The logging verbosity in the terminal and log-file can be set as one of `ALL MARK TRACE DEBUG INFO WARN ERROR FATAL OFF`. + +```yaml +log_level: INFO +``` + +## `behaviour` Behaviour +This sections controls the behaviour of JohnCG during usage. + +### `activate_item_on_add` Automatically activate items after adding +Determiens wether an item should be activated (set as the currently displayed one) when it gets added to the playlist + +```yaml +activate_item_on_add: true +``` + +### `bible_citation_style` Bible citation style +Customize the citation style used for bible-passage lower-thirds. + +Input a citation for *1. Moses chapter 1, verses 2 through 4 and 6 and chapter 7*. + +```yaml +bible_citation_style: 1. Moses 1,2-4.6; 7 +``` + +## `path` Paths of the different files +Stores the paths for the different files used by JohnCG. +It supports both relative and absolute paths. + +```yaml +playlists: Playlists +songs: Songs +psalms: Psalms +pdfs: PDFs +bible: Bibles/Lutherbibel.json +``` + +### `playlists` +Path for the playlist-files. +Playlist-files are json-files but with a `*.jcg` file-extension. + +### `songs` +Path for the song-files. +Songs are stored in the Songbeamer-format. + +### `psalms` +Path for the psalm-files. +Psalm-files are json-files but with a `*.psm` file-extension. + +### `pdfs` +Path for PDF-files. + +### `bible` +Path of the bible-file. + +## `casparcg_connections` Individual CasparCG-connections +Each entry is an individual CasparCG channel. +You can add multiple entries for different channels on the same CasparCG-server and also specify other CasparCG-servers on the network. +All of them get sent the same commands. + +For more information about the `casparcg.config` visit the [CasparCG wiki](https://github.com/CasparCG/help/wiki). + +```yaml +casparcg_connections: + - host: 127.0.0.1 + port: 5250 + channel: 1 + layers: + media: 20 # optional + template: 21 + path: casparcg + # stageview: true +``` + +### `host` +Hostname or IP-address of the CasparCG-server. +Use `127.0.0.1` or `localhost` for a server running on the same machine as JohnCG. + +### `port` +Port used by CasparCG for ACMP control. +Remember to change it in [`casparcg.config`]({% link _setup/casparcg.md %}) too. + +### `channel` +The channel that should be used. + +## `layers` +JohnCG uses two layers: one exclusively for media and one for templates. +The media-layer can be omitted to only display the templates. + +The media-layer is used for: +- song- psalm- and countdown-backgrounds +- media-items +- PDF-slides + +The template-layer is used for: +- song-, psalm and countdown-text +- bible-citations +- text-lower-thirds +- template-items + +Since the AMCP-item sends arbitrary AMCP-commands it isn't bound to the layers specified in the config. + +{: .important } +Make sure the template-layer has a higher number than the media-layer since CasparCG renders higher layer-numbers above lower ones. + +{: .tip } +You can modify the displayed content by sending AMCP-commands through external tools, for example [Bitfocus Companion](https://bitfocus.io/companion). +This could be changing the brightness of the media-player to increase the contrast on the beamer-output through the BRIGHTNESS-mixer. + +## `path` (optional) +Relative or absolute path to a CasparCG-instance. +If this option is specified, JohnCG tries to start CasparCG at startup. + +{: .attention } +If you specifiy multiple CasparCG-connections to the same instance, only specify the autostart-path at one instance + +## Stageview (optional) +Renders a view optimized for performers. +It displays the same as a normal output with the following changes: +- no background-image for songs +- (if available) song-chords diff --git a/docs/_usage/client.md b/docs/_usage/client.md new file mode 100644 index 0000000..da738db --- /dev/null +++ b/docs/_usage/client.md @@ -0,0 +1,6 @@ +--- +title: Client +layout: default +--- +# Client +foobar \ No newline at end of file diff --git a/docs/_usage/elements/Bible.md b/docs/_usage/elements/Bible.md index f448eca..1146d22 100644 --- a/docs/_usage/elements/Bible.md +++ b/docs/_usage/elements/Bible.md @@ -16,12 +16,14 @@ Book of the bible ### Chapter Chapter of the selected book. -**Tip**: Doubleclick on the chapter to clear the selected verses. +{: .tip } +Doubleclick on the chapter to clear the selected verses. ### Verse Select one ore more verses of the selected chapter. -**Tip**: Hold down the shift-key while clicking on a verse to (de)-select the range from the previous clicked verse. +{: .tip } +Hold down the shift-key while clicking on a verse to (de)-select the range from the previous clicked verse. ## CasparCG layers diff --git a/docs/casparcg.md b/docs/casparcg.md new file mode 100644 index 0000000..0ee5dfd --- /dev/null +++ b/docs/casparcg.md @@ -0,0 +1,59 @@ +--- +title: CasparCG +layout: default +nav_order: 3 +--- + +# CasparCG +JohnCG uses CasparCG, an open-ource character-generator, as its rendering engine. +It can play out media-files and programmable HTML-files called templates. + + +## Terminology +### channels +Multiple independant compositions can be created simultaneously and are called **channels**. + +### layers +Each channel has infinite **layers** that are composed on top of each other based on their transparency. + +### producers +Producers render the image and audio displayed in the individual channels. +Producers are for example: +- ffmpeg-input +- media-items +- HTML-templates +- video-input from a Blackmagic DeckLink card +- solid colors +- another producer +- NDI + +### mixer +Mixers modify the media in a layer. +Some mixers are for example: +- position +- scale +- rotation +- opacity +- brightness +- saturation +- contrast +- blend-mode +- clip (masking) +- volume + +### consumer +Consumers output the composed signal of a channel to different interfaces. +Those are for example: +- Blackmagic DeckLink cards +- ffmpeg +- NDI +- screen: a windowed or fullscreen window in the os + +## Further reading +More detailed information can be gathered by: +- [The CasparCG-wiki](https://github.com/CasparCG/help/wiki) +- [amwtech's CasparCG Documentation](https://github.com/amwtech/CasparCG_Documentation) +- [downloading CasparCG](https://github.com/CasparCG/server/releases) and trying around - it's free after all + +{: .tip } +[Bitfocus Companion](https://bitfocus.io/companion) has a good but not fully complete module for controlling CasparCG. You don't need to bother with the actual AMCP-commands and just rendering stuff. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 96209b3..1c4dca7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,40 +1,13 @@ --- title: Home layout: home +nav_order: 1 --- # JohnCG - character generator for song-lyrics and other church-service elements +JohnCG allows you to generate graphics for song lyrics or other church service elements and output them through CasparCG. -Generate grahpics with song-lyrics or other church-service-elements and play them out through CasparCG. +The program runs in a server-client configuration, enabling control from other machines on the same network. This makes it easy to manage and operate from multiple devices. +You can also configure additional outputs as stage monitors to optimize the view for performers. These stage monitor outputs will display the song lyrics without a background and, if available, include chords to assist musicians. -This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details. - -If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages. - -More specifically, the created site: - -- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem -- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages - -Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. - -[Browse our documentation][Just the Docs] to learn more about how to use this theme. - -To get started with creating a site, simply: - -1. click "[use this template]" to create a GitHub repository -2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions - -If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README. - ----- - -[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). - -[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ -[GitHub Pages]: https://docs.github.com/en/pages -[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md -[Jekyll]: https://jekyllrb.com -[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ -[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate diff --git a/docs/requirements.md b/docs/requirements.md index a9f74f1..c2c5c1e 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -1,6 +1,7 @@ --- title: Requirements layout: default +nav_order: 2 --- # Requirements - CasparCG-capable hardware