docs: big docs update part 1

docker/docs.Dockerfile

@@ -3,8 +3,4 @@ FROM squidfunk/mkdocs-material
 # Install additional Python packages (example)
 RUN pip install mkdocs-glightbox mike
 
-COPY ./docs /data/docs-dev
-
 EXPOSE 8000
-
-ENTRYPOINT [ "mike", "serve" ]

docs/configure/channels/transcoding.md

@@ -53,27 +53,3 @@ It consists of two FFMPEG processes, one which performs the per-program transcod
 #### Things to consider
 
 If this mode was "good enough" we probably wouldn't have spent time implementing the other modes! There are a lot of potential issues with this mode; too many to list here.
-
-## Watermarks
-
-Channels can have watermarks to aid in recreating a classic TV experience.
-
-![](/assets/watermark_form.png)
-
-There are many ways to customize watermarks for a channel. Here are some details on specific options:
-
-### Watermark Period
-
-This value can be used to fade a channel's watermark in/out every N minutes.
-
-### Watermark on leading edge
-
-When using intermittent watermarks, use this option to control whether the watermark begins in a visible (true) or hidden (false) state.
-
-### Total watermark duration
-
-This option controls the absolute duration the watermark can be displayed for a given program segment of a channel. Its value takes precedence over the 'watermark period' but does not disable it. For instance, you could configure a watermark period of 5 minutes with total duration of 45 mins. On a show that is one hour, the watermark will fade in/out for the first 45 minutes and then be hidden for the final 15 minutes.
-
-## Overrides
-
-Global settings, such as target resolution, bit rate, and buffer size can be overridden per-channel.

docs/configure/channels/watermarks.md

@@ -0,0 +1,23 @@
+# Channel Watermarks
+
+Channels can have watermarks to aid in recreating a classic TV experience.
+
+![](/assets/watermark_form.png)
+
+There are many ways to customize watermarks for a channel. Here are some details on specific options:
+
+### Watermark Period
+
+This value can be used to fade a channel's watermark in/out every N minutes.
+
+### Watermark on leading edge
+
+When using intermittent watermarks, use this option to control whether the watermark begins in a visible (true) or hidden (false) state.
+
+### Total watermark duration
+
+This option controls the absolute duration the watermark can be displayed for a given program segment of a channel. Its value takes precedence over the 'watermark period' but does not disable it. For instance, you could configure a watermark period of 5 minutes with total duration of 45 mins. On a show that is one hour, the watermark will fade in/out for the first 45 minutes and then be hidden for the final 15 minutes.
+
+## Overrides
+
+Global settings, such as target resolution, bit rate, and buffer size can be overridden per-channel.

docs/configure/ffmpeg/index.md

@@ -0,0 +1,52 @@
+# FFmpeg
+
+Tunarr requires FFmpeg for transcoding / remuxing content when outputting channel streams. Settings relating to transcoding and FFmpeg can be found on the Settings > FFmpeg page.
+
+## Executable Paths
+
+!!! info
+    Only non-Docker installs must provide FFmpeg executable paths. Docker installs come with a bundled version of FFmpeg.
+
+Configure FFmpeg and FFprobe executable paths. Generally, both executables reside in the same directory. We recommend using a [specially built FFmpeg 7.1.1](https://github.com/ErsatzTV/ErsatzTV-ffmpeg/releases/tag/7.1.1) provided by ErsatzTV.
+
+## Global FFmpeg options
+
+### Logging
+
+!!! warn
+    It is recommended to only enable this setting while debugging. If Tunarr experiences an FFmpeg error, it will _still_ generate an error log file that can be used when troubleshooting issues.
+
+Printing or persisting FFmpeg logs to disk is useful when debugging streaming issues. This setting allows for FFmpeg logging to be outputted to Tunarr's stdout stream or to a separate file with a configurable log level. 
+
+### HLS Direct Output Format
+
+When using the HLS Direct stream mode in a channel (see [channel stream modes](../channels/transcoding/#hls-direct)), use this setting to change the output container format for the stream.
+
+### FFmpeg Transcode Path
+
+Configure the path where FFmpeg writes HLS segments for a channel's stream. For instance, if running the standalone Linux binary, Tunarr can write transcoded segments to RAM by setting this option to `/dev/shm`. 
+
+#### Transcode to RAM in Docker
+
+Transcoding to RAM when running Tunarr in Docker requires configuring the container to create a `tmpfs` at startup time:
+
+```yaml title="docker-compose.yml"
+# ... rest of your docker compose
+services:
+    tunarr:
+    # ... rest of your Tunarr service
+    tmpfs:
+        - /transcode:size=10G
+```
+
+Then, in Tunarr, you would set your transcode path to `/transcode`.
+
+## Audio & Subtitles
+
+### Subtitle Extraction
+
+If content in your channels have embedded, text-based subtitles, this option enables Tunarr to extract subtitles from media files in order to subsequently burn the subtitles. Extract embedded text-based subtitles is currently a requirement for using said subtitle streams. Each hour Tunarr will scan the guide for upcoming media, find which items have embedded text-based subtitles, and then run extraction. This can be a resource-intensive process, so in general, sidecar text-based subtitles are preferable.
+
+### Language Preference
+
+Currently, language preferences can only be configured globally. Use this setting to set an ordered list of preferred audio languages. The first matching audio language stream for a given piece of content will be chosen.

docs/configure/ffmpeg/transcode_config.md

@@ -0,0 +1,38 @@
+# Transcode Configs
+
+Transcode Configurations provide Tunarr with a set of parameters to produce a normalized output stream for a given channel. These configurations are responsible for options like hardware acceleration, output video/audio formats, bit rates, and more. Transcode configurations are applied per-channel. This page explores some of these options at a high level.
+
+## Video
+
+Configure output video parameters, such as format, hardware acceleration, and resolution.
+
+<figure markdown="span">
+    ![](../../assets/transcode_configs_video.png)
+    <figcaption>Video Options as of 0.22.11</figcaption>
+</figure>
+
+## Audio
+
+Configure output audio parameters, such as format, channels, and sample rate.
+
+<figure markdown="span">
+    ![](../../assets/transcode_configs_audio.png)
+    <figcaption>Audio Options as of 0.22.11</figcaption>
+</figure>
+
+Notes about audio settings:
+
+1. "Audio Channels" uses whole number channel counts. For instance, a 5.1 configuration would be configured as "6".
+2. "Audio Format" can be set to "copy" to passthrough audio
+
+## Errors
+
+Configure how Tunarr reacts to transcoding errors. Tunarr can be configured to output an error image on the screen, with or without audio.
+
+!!! info
+    More configurable error options are tracked in [chrisbenincasa/tunarr#1292](https://github.com/chrisbenincasa/tunarr/issues/1292)
+
+<figure markdown="span">
+    ![](../../assets/transcode_configs_error.png)
+    <figcaption>Error Options as of 0.22.11</figcaption>
+</figure>

docs/configure/media_sources/index.md

@@ -0,0 +1,3 @@
+# Media Sources
+
+Tunarr finds media to use in channels from one or more "Media Sources". Tunarr supports [Plex](./plex.md), [Jellyfin](./jellyfin.md), and [Emby](./emby.md) as Media Sources. In alpha versions, Tunarr also supports [Local](./local.md) Media Sources.

docs/configure/media_sources/jellyfin.md

@@ -0,0 +1,79 @@
+# Jellyfin
+
+Tunarr can source content from Jellyfin servers. All metadata is provided from the Jellyfin server.
+
+## Connect
+
+Connect Tunarr to Jellyfin servers by navigating to Settings > Sources. There are two methods of authentication that can be used to connect a Jellyfin server.
+
+<figure markdown="span">
+    ![](../../assets/media_sources_add_dropdown.png)
+</figure>
+
+After clicking "Jellyfin" you will be presented with a dialog to configure the connection.
+
+<figure markdown="span">
+    ![](../../assets/add_jellyfin_media_source_dialog.png)
+</figure>
+
+### API Key
+
+The simplest way to connect Jellyfin is to generate an API Key in the Jellyfin admin dashboard specifically for Tunarr. Navigate to the Jellyfin Admin Dashboard > API Keys and then click "New API Key"
+
+<figure markdown="span">
+    ![](../../assets/jellyfin_api_keys.png)
+</figure>
+
+Once you've generated a new API Key, you can copy + paste the key into the "Add Jellyfin Media Source" dialog launched from the Settings > Sources page in Tunarr.
+
+### Username / Password
+
+!!! info
+    Tunarr does **NOT** persist your Jellyfin password anywhere. However, it does issue a request to the Jellyfin API to exchange the username / password combination for an API Key, which is then persisted to the Tunarr DB.
+
+If you cannot (i.e. you are not an Admin), or would not like to, use an API Key, you can use your username and password to connect to Jellyfin. 
+
+## Synchronization
+
+!!! info
+    This is an alpha-only feature that will be available in v1.0
+
+Tunarr will periodically synchronize chosen Jellyfin libraries. Synchronizing is a one-way import of Jellyfin metadata into Tunarr. Tunarr **never** mutates Jellyfin data. Importing metadata from Jellyfin allows for a richer search and scheduling experience.
+
+After connecting your Jellyfin server, find the server in the Media Sources table and click the "Edit Libraries" button:
+
+<figure markdown="span">
+    ![](../../assets/media_sources_edit_libraries.png)
+</figure>
+
+You will be presented with the Jellyfin libraries that Tunarr is able to sync:
+
+<figure markdown="span">
+    ![](../../assets/media_sources_enable_libraries.png)
+</figure>
+
+Upon selecting libraries, they will be queued for synchronization. Tunarr will only sync one library per-source at a time. By default, Media Source libraries are all synchronized once every 6 hours. This period can be configured on the Media Source settings page.
+
+## Stream from Disk
+
+When using external Media Sources, it is recommended to ensure Tunarr has access to the underlying media files, which can greatly improve streaming performance and stability while reducing network activity. There are 2 ways to achieve this:
+
+1. Ensure that Tunarr has access to the media file paths as seen by Jellyfin. Depending on your deployment, this could mean creating the same bind mounts to a Docker container or ensuring that Tunarr has access to the same shares, etc. that Jellyfin does.
+2. Configure "path replacements" for the Jellyfin server to "transform" Tunarr-visible paths to ones reported by Jellyfin.
+
+Option 1 is simpler and requires no additional configuration within Tunarr. 
+
+### Configuring Path Replacements (stable)
+
+On current stable versions path replacements can only be configured once for all servers, globally.
+
+First change the "Stream Path" mode to "Direct"
+
+<figure markdown="span">
+    ![](../../assets/media_source_direct_path.png)
+    <figcaption>Direct stream path mode</figcaption>
+</figure>
+
+Then, configure your stream path. Tunarr uses prefix-matching for the "original" path to replace.
+
+<figure markdown="span">

docs/configure/media_sources/local.md

@@ -0,0 +1,21 @@
+---
+status: new
+---
+
+# Local
+
+!!! info
+    This feature is only available on alpha builds! It will be released as part of Tunarr 1.0.
+
+Local Media Sources allow scheduling media from your filesystem (i.e. no media server is necessary).
+
+Tunarr traverses folders for Local Media Sources to discover metadata and media files which can then be scheduled to channels.
+
+Currently, Tunarr supports the following media types for Local sources:
+
+1. Movies
+2. Shows
+
+# Metadata
+
+## Generating Metadata

docs/configure/media_sources/plex.md

@@ -0,0 +1,75 @@
+# Plex
+
+Tunarr can source content from Plex servers. All metadata is provided from the Plex server.
+
+## Connect
+
+Connect Tunarr to Plex servers by navigating to Settings > Sources.
+
+![add_plex_media_source](../../assets/media_sources_plex_add.png)
+
+### Auto
+
+Automatic connection launches a Plex sign in pop-up. After successful sign-in, Tunarr will use Plex APIs to discover all available Plex servers for your Plex user and subsequently add reachable ones to Tunarr.
+
+### Manual
+
+If you do not want to, or can't, use automatic server discovery, Plex server details can be manually added to Tunarr. You will need to obtain a Plex token by following [these instructions](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/).
+
+## Synchronization
+
+!!! info
+    This is an alpha-only feature that will be available in v1.0
+
+Tunarr will periodically synchronize chosen Plex libraries. Synchronizing is a one-way import of Plex metadata into Tunarr. Tunarr **never** mutates Plex data. Importing metadata from Plex allows for a richer search and scheduling experience.
+
+After connecting your Plex server, find the server in the Media Sources table and click the "Edit Libraries" button:
+
+<figure markdown="span">
+    ![](../../assets/media_sources_edit_libraries.png)
+</figure>
+
+You will be presented with the Plex libraries that Tunarr is able to sync:
+
+<figure markdown="span">
+    ![](../../assets/media_sources_enable_libraries.png)
+</figure>
+
+Upon selecting libraries, they will be queued for synchronization. Tunarr will only sync one library per-source at a time. By default, Media Source libraries are all synchronized once every 6 hours. This period can be configured on the Media Source settings page.
+
+## Stream from Disk
+
+When using external Media Sources, it is recommended to ensure Tunarr has access to the underlying media files, which can greatly improve streaming performance and stability while reducing network activity. There are 2 ways to achieve this:
+
+1. Ensure that Tunarr has access to the media file paths as seen by Plex. Depending on your deployment, this could mean creating the same bind mounts to a Docker container or ensuring that Tunarr has access to the same shares, etc. that Plex does.
+2. Configure "path replacements" for the Plex server to "transform" Tunarr-visible paths to ones reported by Plex.
+
+Option 1 is simpler and requires no additional configuration within Tunarr. 
+
+### Configuring Path Replacements (stable)
+
+On current stable versions path replacements can only be configured once for all servers, globally.
+
+First change the "Stream Path" mode to "Direct"
+
+<figure markdown="span">
+    ![](../../assets/media_source_direct_path.png)
+    <figcaption>Direct stream path mode</figcaption>
+</figure>
+
+Then, configure your stream path. Tunarr uses prefix-matching for the "original" path to replace.
+
+<figure markdown="span">
+    ![](../../assets/media_source_path_replacement_old.png)
+</figure>
+
+### Configuring Path Replacements (alpha)
+
+!!! info
+    Alpha versions allow configuring path replacements per-media-source.
+
+To configure path replacements (Option 2), click on the "Edit" button on the Media Source row. From here, you can add one or more path replace patterns to potentially apply to incoming media.
+
+<figure markdown="span">
+    ![](../../assets/media_source_path_replace.png)
+</figure>

docs/configure/system/ffmpeg.md

@@ -1,15 +0,0 @@
-# FFmpeg
-
-Many settings about how Tunarr transcode content can be configured on the FFmpeg page
-
-## Executable Paths
-
-Configure FFmpeg and FFprobe executable paths. Generally, both executables reside in the same directory.
-
-!!! warning
-
-    On 2024/10/01, an [exploit](https://www.exploit-db.com/exploits/52079) affecting dizqueTV was reported. This mainly affects instances of dizqueTV that were exposed to the public internet. The exploit affected Tunarr as well, and was patched in 0.14.0. This exploit is the reason ["admin mode"](/configure/system/security#admin-mode) exists.
-
-    Additionally, we consider exposing Tunarr publicly to be an unsupported use-case. While we take security extremely seriously, this path is not one we currently test against. We would not recommend exposing Tunarr to the public via port forwarding at this point.
-
-This setting can only be configured in ["admin mode"](/configure/system/security#admin-mode) due to its sensitivity (Tunarr attempts to run the inputted executable path!).

docs/configure/system/security.md

@@ -1,134 +0,0 @@
-# Security
-
-## Admin mode
-
-Due to [this exploit](https://www.exploit-db.com/exploits/52079) Tunarr supports "admin mode". By default, admin mode is disabled. Some settings, like FFmpeg executable paths, can only be edited in the Tunarr UI when Tunarr is running in admin mode. **NOTE**: This shouldn't be confused with Windows "run as administrator"!
-
-There are several ways to update sensitive settings that require admin mode.
-
-### Running in admin mode
-
-### Standalone binary
-
-Pass the `--admin` flag when running the executable, e.g.:
-
-```bash
- ./tunarr --admin
-```
-
-or on Windows:
-
-```powershell
-.\tunarr.exe --admin
-```
-
-You can also use an environment variable:
-
-```bash
-TUNARR_SERVER_ADMIN_MODE=true ./tunarr
-```
-
-and again on Windows (Powershell):
-
-```powershell
-$Env:TUNARR_SERVER_ADMIN_MODE='true'
-.\tunarr.exe
-```
-
-or Command Prompt:
-
-```
-set TUNARR_SERVER_ADMIN_MODE=true
-.\tunarr.exe
-```
-
-### Docker
-
-Start Tunarr server with the `admin` argument
-
-```bash
-docker run ... chrisbenincasa/tunarr:latest -- /tunarr/tunarr --admin
-```
-
-!!! note
-
-    <a href="https://github.com/chrisbenincasa/tunarr/issues/900" target="_blank">chrisbenincasa/tunarr#900</a> tracks simplifying running commands against Tunarr within a container.
-
-or with the environment variable
-
-```bash
-docker run -e 'TUNARR_SERVER_ADMIN_MODE=true' ... chrisbenincasa/tunarr
-```
-
-### Updating sensitive values directly
-
-Tunarr supports other run modes other than server. One is updating settings.json values directly. This can be done against a running Tunarr server without admin mode enabled.
-
-```bash
-./tunarr.sh settings update --settings.ffmpeg.ffmpegExecutablePath="FFMEPG_PATH" --settings.ffmpeg.ffprobeExecutablePath="FFPROBE_PATH"
-```
-
-This also works with Docker
-
-```bash
-docker run --rm \
-  ...
-  chrisbenincasa/tunarr -- /tunarr/tunarr \
-  settings update \
-  settings.ffmpeg.ffmpegExecutablePath="FFMEPG_PATH" \
-  settings.ffmpeg.ffprobeExecutablePath="FFPROBE_PATH"
-```
-
-## Trust proxy
-
-When running Tunarr behind a reverse proxy server for HTTPS support, you will need to enable "trust proxy" for the generated XMLTV and M3U files to contain the correct protocol (e.g., `http` or `https`) and host. Without "trust proxy" enabled, Tunarr will not honor the `X-Forwarded-Proto` and `X-Forwarded-Host` headers forwarded from the reverse proxy.
-
-There are several ways to enable "trust proxy".
-
-### Standalone script
-
-Pass the `--trustProxy` flag when running the script, e.g.:
-
-```bash
- ./tunarr --trustProxy
-```
-
-or on Windows:
-
-```powershell
-.\tunarr.exe --trustProxy
-```
-
-You can also use an environment variable:
-
-```bash
-TUNARR_SERVER_TRUST_PROXY=true ./tunarr
-```
-
-and again on Windows (Powershell):
-
-```powershell
-$Env:TUNARR_SERVER_TRUST_PROXY='true'
-.\tunarr.exe
-```
-
-or Command Prompt:
-
-```
-set TUNARR_SERVER_TRUST_PROXY=true
-.\tunarr.exe
-```
-
-### Docker
-
-Start Tunarr server with the `trustProxy` argument
-
-```bash
-docker run ... chrisbenincasa/tunarr:latest -- /tunarr/tunarr --trustProxy
-```
-
-or with the environment variable
-
-```bash
-docker run -e 'TUNARR_SERVER_TRUST_PROXY=true' ... chrisbenincasa/tunarr
-```

docs/getting-started/setup.md

@@ -20,16 +20,12 @@ Click the "Add" button, followed by your source. For Plex, you can choose Auto t
 
 ### FFMPEG
 
-Tunarr also requires [FFmpeg](https://ffmpeg.org/). FFmpeg is used to normalize channel video / audio streams for seamless playback, interleave your "flex" content, and more. Tunarr defaults to looking for the FFmpeg executable at `/usr/bin/ffmpeg`. If no executable is found, you can change the path in the FFmpeg settings page. The minimum known supported version of FFmpeg is 6.1. The recommended version is at least 7.0.
+Tunarr also requires [FFmpeg](https://ffmpeg.org/). FFmpeg is used to normalize channel video / audio streams for seamless playback, interleave your "flex" content, and more. Tunarr defaults to looking for the FFmpeg executable at `/usr/bin/ffmpeg`. If no executable is found, you can change the path in the FFmpeg settings page. The minimum known supported version of FFmpeg is 6.1. The recommended version is 7.1.1.
 
 Please note that FFmpeg is provided in Tunarr Docker images, so Docker users should not need to make any adjustments to this page.
 
 ![Welcome Page With FFMPEG](../assets/welcome_page_ffmpeg_installed.png)
 
-!!! info
-
-    In order to set the FFmpeg path, Tunarr must be run in "admin mode". Please see the [Security](/configure/system/security) page for more details on how to run Tunarr in admin mode and why this is necessary.
-
 Click "FINISH" and you will be brought to the new channel page to [create your first channel](/configure/channels/properties).
 
 ![Finish](../assets/setup-finish.png)

docs/index.md

@@ -13,7 +13,6 @@ Tunarr was originally a fork of [**dizqueTV**](https://github.com/vexorian/dizqu
 Tunarr has the following goals:
 
 - Modernize the stack, both backend and frontend
-- Provide an [migration path](getting-started/setup.md#migrating-from-dizquetv) for existing users
-- Stabilize the program, fix bugs, and improve performance (Tunarr currently is developed and tested on Node 20.11.1, which offers [non-trivial performance improvements](https://blog.rafaelgss.dev/state-of-nodejs-performance-2023) over previous versions)
+- Stabilize the program, fix bugs, and improve performance (Tunarr currently is developed and tested on Node 22.13.1, which offers [non-trivial performance improvements](https://blog.rafaelgss.dev/state-of-nodejs-performance-2023) over previous versions)
 - Modernize and "prettify" the Web UI
 - And of course, **Add a ton great new features!**

docs/stylesheets/extra.css

@@ -16,3 +16,12 @@
   --md-primary-fg-color: #008c93;
   --md-accent-fg-color: #004b79;
 }
+
+:root {
+  --md-status--alpha: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2M7 9.5C7 8.7 7.7 8 8.5 8s1.5.7 1.5 1.5S9.3 11 8.5 11 7 10.3 7 9.5m5 7.73c-1.75 0-3.29-.73-4.19-1.81L9.23 14c.45.72 1.52 1.23 2.77 1.23s2.32-.51 2.77-1.23l1.42 1.42c-.9 1.08-2.44 1.81-4.19 1.81M15.5 11c-.8 0-1.5-.7-1.5-1.5S14.7 8 15.5 8s1.5.7 1.5 1.5-.7 1.5-1.5 1.5Z"/></svg>')
+}
+
+.md-status--alpha::after {
+  mask-image: var(--md-status--alpha);
+  -webkit-mask-image: var(--md-status--alpha);
+}

mkdocs.yml

@@ -43,14 +43,24 @@ nav:
       - Run: getting-started/run.md
       - Setup: getting-started/setup.md
   - Configure:
+      - Media Sources:
+          - configure/media_sources/index.md
+          - Plex: configure/media_sources/plex.md
+          - Jellyfin: configure/media_sources/jellyfin.md
+          - Emby: configure/media_sources/emby.md
+          - Local: configure/media_sources/local.md
+      - FFmpeg:
+          - configure/ffmpeg/index.md
+          - Transcode Configs: configure/ffmpeg/transcode_config.md
       - Channels:
           - configure/channels/index.md
           - Properties: configure/channels/properties.md
           - Flex: configure/channels/flex.md
           - EPG: configure/channels/epg.md
           - Transcoding: configure/channels/transcoding.md
+          - Watermarks: configure/channels/watermarks.md
       - Programming: configure/programming.md
-    - Scheduling Tools: 
+      - Scheduling:
           - configure/scheduling-tools/index.md
           - Slot Editor: configure/scheduling-tools/random-slots.md
           - Time Slots: configure/scheduling-tools/time-slots.md
@@ -61,10 +71,6 @@ nav:
           - configure/library/index.md
           - Filler: configure/library/filler.md
           - Custom Shows: configure/library/custom-shows.md
-    - System:
-      - configure/system/index.md
-      - Security: configure/system/security.md
-      - FFmpeg: configure/system/ffmpeg.md
       - Clients:
           - configure/clients/index.md
           - Plex: configure/clients/plex.md
@@ -93,8 +99,8 @@ extra_css:
   - stylesheets/extra.css
 
 extra:
-  version:
-    provider: mike
+  status:
+    alpha: Alpha
 
 plugins:
   - glightbox