docs: first set of documentation improvements and changes

.github/workflows/docs.yml

@@ -29,5 +29,5 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material
+      - run: pip install mkdocs-material mkdocs-glightbox
       - run: mkdocs gh-deploy --force

docker/docs.Dockerfile

@@ -0,0 +1,4 @@
+FROM squidfunk/mkdocs-material
+
+# Install additional Python packages (example)
+RUN pip install mkdocs-glightbox

docker/example.compose.yaml

@@ -3,7 +3,7 @@ services:
   tunarr:
     # image: chrisbenincasa/tunarr:edge
     # Uncomment along with runtime below to enable HW accel
-    image: chrisbenincasa/tunarr:edge-nvidia
+    image: chrisbenincasa/tunarr:edge
     container_name: tunarr
     ports:
       - 8088:8000

docker/nexe-windows.Dockerfile

@@ -1,15 +0,0 @@
-FROM mcr.microsoft.com/windows/nanoserver:ltsc2022 as base
-
-# installs Chocolatey (Windows Package Manager)
-RUN Set-ExecutionPolicy Bypass -Scope Process -Force;
-RUN [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
-RUN iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'));
-
-# download and install Node.js
-RUN choco install nodejs --version="20.12.0"
-
-# verifies the right Node.js version is in the environment
-RUN node -v
-
-# verifies the right NPM version is in the environment
-RUN npm -v

docs/configure/channels/properties.md

@@ -1,6 +1,6 @@
 # Properties
 
-Choose a channel a name. Optionally, you can also add a thumbnail by uploading an image. This will be the logo visible within your Plex/Jellyfin channel guide. Transparent .png files are supported. 
+Choose a channel a name. Optionally, you can also add a thumbnail by uploading an image or providing an image URL. This will be the logo visible within your IPTV client's channel guide. Transparent .png files are supported. 
 
 On-Demand will allow your channels to behave similar to streaming services, where the watch states will only progress while you're actively viewing the channel. This is disabled by default, which means by default channels will behave similar to traditional televison where watch states will progress without you actively viewing the channel.
 

docs/configure/clients/index.md

@@ -1,3 +1,3 @@
 # Clients
 
-Once you have your channels created within Tunarr, you are ready to configure your clients. We currently have a guide written for [Plex](/configure/clients/plex), but [Jellyfin](/configure/clients/jellyfin) and Emby should work as well. You can also utilize generated M3U files with any 3rd party IPTV player app.
+Once you have your channels created within Tunarr, you are ready to configure your clients. We currently have a guide written for [Plex](/configure/clients/plex), but [Jellyfin](/configure/clients/jellyfin) and Emby should work as well. You can also utilize generated M3U files with any 3rd party IPTV player app.

docs/configure/programming.md

@@ -28,10 +28,12 @@ Select "ADD ITEMS" to save your changes.
 
 ![Add item](/assets/programming-additem.png)
 
-By default, your episode ordering will be alphabetical (by show name) and in the proper season order. In this example, we have two shows and the first show will play in its entirety progressing from specials through all seasons, and only then will the next show start playing. 
+By default, your shows are ordered alphabetically (by show name) and episodes within are in proper season order. In this example, we have two shows and the first show will play in its entirety progressing from specials through all seasons, and only then will the next show start playing. 
 
 ![Media added](/assets/programming-mediaadded.png)
 
+To make the viewing experience more interesting and authentic, you will want to use Tunarr's [scheduling tools](../scheduling-tools/) to reorder and group content.
+
 If we instead wanted this similar to what we'd see on traditional television, select "SORT" and choose either Block Shuffle or Cyclic Shuffle. 
 
 ![Shuffle](/assets/programming-shuffle.png)

docs/configure/scheduling-tools/index.md

@@ -1,13 +1,17 @@
 # Scheduling Tools
 
-Tunarr offers a range of tools for scheduling your content.
+Tunarr offers a range of tools for modifying channel schedules.
 
-[Time Slots](/configure/scheduling-tools/time-slots) are the best option to most closely mimic traditional television but can be a bit laborious to configure. 
+* [Slot Editor](random-slots.md) allows assigning programming to "slots" of fixed or dynamic duration. Slots can then be played back sequentially or at random when generating a schedule.
 
-[Random Slots](/configure/scheduling-tools/random-slots) accomplishes the same as Time Slots, but requires much less work to setup due to randomizing when each show is aired. 
+* [Time Slots](time-slots.md) mimic traditional TV scheduling, where programs are assigned to a particular start time and duration.
 
-[Balance](/configure/scheduling-tools/balance) let's you pick the weight for your shows to air some shows more frequently than others. 
+* [Block Shuffle](block-shuffle.md) is a simpler version of slot editor. Randomly chooses "blocks" of programming of a chosen size.
 
-[Replicate](/configure/scheduling-tools/replicate) will create copies of the same schedule and play them in sequence. This typically is not needed as Tunarr already handles replaying a schedule once complete. 
+* [Cyclic Shuffle](cyclic-shuffle.md)
 
-[Consolidate](/configure/scheduling-tools/consolidate) merges contiguous match flex and redirect blocks into singular spans. 
+* [Balance](balance.md) lets you pick the weight for your shows to air some shows more frequently than others. 
+
+* [Replicate](replicate.md) will create copies of the same schedule and play them in sequence. This typically is not needed as Tunarr already handles replaying a schedule once complete. Some use this as an intermediate tool before applying other tools, like balance.
+
+* [Consolidate](consolidate.md) merges contiguous match flex and redirect blocks into singular spans. 

docs/configure/scheduling-tools/random-slots.md

@@ -1,18 +1,83 @@
-# Random Slots
+# Slots Editor
 
-Random Slots allow you to schedule specific shows to run during randomized time slots. 
+Slots Editor allows you to schedule programming in "slots". This tool is powerful and flexible and allows building various schedule types.
 
-To schedule Random Slots for your channel programming, select "TOOLS", then "Random Slots".
+To use Slots Editor for your channel programming, select "TOOLS", then "Slots Editor".
 
-![Random Slots](/assets/scheduling-tools-random_slots.png)
+![Slots Editor](/assets/scheduling-tools-random_slots.png)
 
-In this example, we want both "Yu-Gi-Oh! Duel Monsters" and "Batman Beyond" to air in 30 minute blocks. We have Pad Times set to 00:00 and 00:30, so the episodes will always try to air right at those times by using [Flex](/configure/channels/flex) to fill the empty time. 
+## Slot Configuration
+
+Each slot is configured with a few parameters.
+
+![Add/Edit Slot Dialog](/assets/slot-editor-dialog.png)
+
+When creating a programming slot, you choose between "Fixed" and "Dynamic" length.
+
+* **Fixed** length slots run for an absolute duration (e.g. 30 mins)
+* **Dynamic** length slots run for an absolute _count_ of programs (e.g. 3 episodes)
+
+The **Cooldown** parameter controls a frequency cooldown; it is used when using "random" mode scheduling, which picks slots at random during schedule generation.
+
+Some programming types also allow configuration of the **order** in which their constituents are scheduled. This controls the playback order; for example, if using "Next" ordering for a TV Show, episodes will be iterated over in episode order during scheduling.
+
+## Scheduling Configuration
+
+### Slot Choice
+
+The options for how slots are chosen during schedule generation is part of what makes Slot Editor quite powerful. There are two main ways the scheduler can choose slots during schedule generation: **random** and **sequential**.
+
+* **Random** choice chooses slots randomly. This slot choice has two subtypes: uniform and weighted.
+    * **Uniform** random slot choice assigns equal weight to all slots. As scheduling progresses, each slot has an equal chance of being chosen for playback
+    * **Weighted** slot choice allows you to modify the weights of each slot relative to one another
+* **Sequential** (or **None**) chooses slots in the _order they are defined in the editor itself_. This allows for creation of finely tuned sequences of programming, airing in a particular order
+
+### Schedule Options
+
+#### Pad Times
+
+Padding slots ensures that slots will always finish on a set of particular end times (e.g. :00 and :30). To achieve this, the scheduler will add ["flex" time](/configure/library/filler/#filler) to round each slot to the selected time pad.
+
+#### Pad Style
+
+Configure how "pad times" is applied. 
+
+* **Pad Slot**: Align slot start times to the specified pad time.
+* **Pad Episode**: Align episode start times (within a slot) to the specified pad time. NOTE: Depending on slot length and the chosen pad time, this could potentially create a lot of flex.
+
+#### Flex Style
+
+Determines how flex is added to a slot to fill in leftover time, either due to being a "fixed" duration slot or due to a pad times setting.
+
+* **Between**: Flex time is added between videos within a slot, if there are multiple
+* **End**: Flex time is added at the end of the slot
+
+#### Days to Precalculate
+
+Currently, Tunarr can only statically precalculate a schedule. This option determines how far into the future the schedule will be calculated before saving the lineup for playback.
+
+## Presets
+
+The Slot Editor also comes with some preset configurations based on the content of the channel.
+
+### Cyclic Shuffle
+
+This is an implementation of the original "cyclic shuffle" dizqueTV programming tool. By default, this preset schedules 1 block per program group, with a dynamic duration of 1 program per block. 
+
+## Example
+
+In this example, we want "30 Rock and "Arrested Development" to air in 30 minute blocks. We have Pad Times set to 00:00 and 00:30, so the episodes will always try to air right at those times by using [Flex](/configure/channels/flex) to fill the empty time. 
 
 ![Random Slots example](/assets/scheduling-tools-random_slots_example.png)
 
-See below for an example of our current schedule. Note that due to the schedule starting at 4:43pm, the first episode will finish airing at 5:05pm, so a larger-than-normal amount of Flex time will be used to get the schedule back on track to have things air at 00:00 and 00:30. After the first airing, we see things normalized with a more appropriate 8-10 minutes of Flex after each episode. 
+Below is a generated schedule with this configuration. A few things to note:
 
-![Random Slots preview](/assets/scheduling-tools-random_slots_preview.png)
+* 
+
+<figure markdown="span">
+  ![Random Slots preview](/assets/scheduling-tools-random_slots_preview.png)
+  <figcaption>Example generated schedule</figcaption>
+</figure>
 
 In this example, one of our shows has far more episodes than the other but by default the episode Distribution is Uniform so the shows will be ordered with equal priority. If we instead wanted "Yu-Gi-Oh! Duel Monsters" to air 70% of the time, and "Batman Beyond" to air 30% of the time, we would set Distribution to Weighted and adjust the sliders. 
 

docs/getting-started/run.md

@@ -79,7 +79,7 @@ Tunarr has various command line / environment variables for configuration. These
 | `TUNARR_USE_WORKER_POOL` | N/A | FALSE | Set to true to enable experimental support for Tunarr's worker threads | 
 | `TUNARR_WORKER_POOL_SIZE` | N/A | `cpus().length` | Control the number of worker threads Tunarr creates in its pool. It's recommended to use no more than the number of CPUs on the host system | 
 
-## Hardware Encoding
+## Hardware Transcoding
 
 ### Nvidia
 
@@ -250,3 +250,27 @@ Save the following launchd configuration to `~/Library/LaunchAgents/tunarr.xml`.
 #### NSSM (Windows)
 
 [NSSM](https://nssm.cc/) is the recommended way to run Tunarr as a background task in Windows. It is recommended to configure NSSM to run Tunarr as the currently logged in user.
+
+1. [Download NSSM](https://nssm.cc/ci/nssm-2.24-101-g897c7ad.zip) from its website. The latest version is recommended because it is more compatible with the latest versions of Windows.
+2. Once unzipped, you will obtain the `nssm.exe` file (inside `win64` folder). Create a folder called `nssm` and place the `nssm.exe` file inside it. Then move this folder to the `Program Files` folder. The final path for NSSM will be: `C:\Program Files\nssm\nssm.exe`
+3. Insert the NSSM file into the Windows environment variables. If you already know how to do this, skip directly to step 6.
+4. Open the start menu and type “Path.” At this point, “edit system environment variables” will appear in the search. Click on it and a new window will open with the words “environment variables...” at the bottom. Click on it.
+5. Another window will open and in the upper section we will need to select “Path” and then click on “Edit.” In this last window that opens, we will click on “New” and enter this path: `C:\Program Files\nssm`. Now we can click on OK and close all the other windows that were previously open by clicking on OK again.
+6. Open "Command Prompt" as administrator, type `nssm install`, and press enter. The nssm configuration window will open. What we are interested in for now is filling in some fields in the ‘Application’ and “Details” tabs.
+7. The first field to fill in is the service name at the bottom, in our example the name entered will simply be “Tunarr”.
+8. Assuming you've placed our `tunarr.exe` in the following path: `C:\Program files\tunarr\tunar.exe`, in the “Application” tab, simply copy and paste the entire path, including .exe, into the “Path” field. If you have Tunarr in a different location, use that path instead.
+9. In the “startup folder” field, enter only the path to the folder, so in our example it will be `C:\Program files\tunarr` (without quotation marks). The “arguments” field can be left blank, but if you need a different port at this stage that you have not yet changed within Tunarr, you can add `--port 8001` to change the port to 8001, or one of your choice (useful when using a program, such as dizqueTV, that has already occupied port 8000).
+10. Now go to the “Details” tab. Everything here is less important. Just enter “Tunarr” in the “Display name” field and something of your choice in the ‘Description’ field. Leave the startup type set to “Automatic.”
+11. Click on “Install service” and Tunarr will finally be installed as a service
+
+##### Updating Tunarr within NSSM
+
+From now on, to update tunarr, we will first have to stop the service. 
+1. Click on the start menu and search for “services”. Click on the result.
+2. On the next screen with the list of all services, right-click on Tunarr and click on “stop.” 
+3. Replace the .exe file with the updated executable, return to the services screen, right-click on Tunarr, and select “start”
+
+##### Converting Tunarr to an NSSM service
+
+If you are converting from a previously used Tunarr, please note that the main Tunarr folder will now be moved to another location, so the new Tunarr that starts will actually behave as if it were a new installation. To restore the entire configuration, you will need to copy the contents of the Tunarr folder in the path usually used by the program `%appdata%\ tunarr` and paste it into the following location: `C:\Windows\System32\config\systemprofile\AppData\Roaming\tunarr`
+This will be the new location for the database, channels, and everything else (obviously, this must be done after stopping the tunarr service and then restarting it as explained above).

docs/misc/common-issues.md

@@ -29,4 +29,7 @@ Head over to Tunarr > Settings > SOURCES > Select the pencil icon next to your s
 
 ![Auto-update channels disabled](/assets/serversettings-autoupdatechannels.png)
 
-If this is already unchecked, see [Issue #818](https://github.com/chrisbenincasa/tunarr/issues/818) to track this issue. 
+If this is already unchecked, see [Issue #818](https://github.com/chrisbenincasa/tunarr/issues/818) to track this issue. 
+
+## Channel icons missing
+

mkdocs.yml

@@ -52,8 +52,8 @@ nav:
     - Programming: configure/programming.md
     - Scheduling Tools: 
       - configure/scheduling-tools/index.md
+      - Slot Editor: configure/scheduling-tools/random-slots.md
       - Time Slots: configure/scheduling-tools/time-slots.md
-      - Random Slots: configure/scheduling-tools/random-slots.md
       - Balance: configure/scheduling-tools/balance.md
       - Replicate: configure/scheduling-tools/replicate.md
       - Consolidate: configure/scheduling-tools/consolidate.md
@@ -77,6 +77,7 @@ nav:
 
 markdown_extensions:
   - admonition
+  - md_in_html
   - toc:
       permalink: true
   - pymdownx.details
@@ -93,4 +94,7 @@ extra_css:
 
 extra:
   version:
-    provider: mike
+    provider: mike
+
+plugins:
+ - glightbox

scripts/run-docs-local.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+docker build -f ./docker/docs.Dockerfile -t chrisbenincasa/tunarr-docs .
+
+docker run --rm -it -p 8088:8000 -v "${PWD}":/docs chrisbenincasa/tunarr-docs