add documentation (#145)

* start to reorganize documentation

* revert readme tag changes

* revert readme tag changes pt2

* doc updates; doc theme updates

* doc updates

* publish docs from documentation branch

* use favicon for docs

* create channel

* collections, jellyfin client, schedule items and playout docs

* channels dvr

* tivimate

* scale tivimate screenshots

* add channels dvr server setup

* add copyright and social

* Added UnRAID Docker install, formatting fixes (#100)

Co-authored-by: Thaddeus Cooper <redacted@redacted.co.nz>

* minor doc updates

* readme tweak

* add basic plex documentation

Co-authored-by: suckerface <9060047+suckerface@users.noreply.github.com>
Co-authored-by: Thaddeus Cooper <redacted@redacted.co.nz>

.editorconfig

@@ -79,3 +79,7 @@ indent_size=2
 indent_style=space
 indent_size=4
 tab_width=4
+
+[*.yml]
+indent_style = space
+indent_size = 2

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v1
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CUSTOM_DOMAIN: ersatztv.org

ErsatzTV/Pages/PlexMediaSources.razor

@@ -128,10 +128,10 @@
         }
     }
 
-    private void PlexChanged(object sender, EventArgs e)
+    private async void PlexChanged(object sender, EventArgs e)
     {
-        InvokeAsync(LoadMediaSources);
+        await InvokeAsync(LoadMediaSources);
-        InvokeAsync(StateHasChanged);
+        await InvokeAsync(StateHasChanged);
     }
 
     void IDisposable.Dispose() => Locker.OnPlexChanged -= PlexChanged;

README.md

@@ -2,6 +2,8 @@
 
 **ErsatzTV** is pre-alpha software for configuring and streaming custom live channels using your media library. The software is currently unstable and under active development.
 
+Documentation is available at [ersatztv.org](https://ersatztv.org/).
+
 Want to join the community or have a question? Join us on [Discord](https://discord.gg/hHaJm3yGy6).
 
 ## Current Features
@@ -12,69 +14,24 @@ Want to join the community or have a question? Join us on [Discord](https://disc
 - Collection-based scheduling, with collections containing television shows, seasons, episodes and movies
 - Powerful scheduling options such as chronological collection playback throughout the day or over multiple days
 - [Hardware-accelerated transcoding](#Hardware-Transcoding) options (QSV, NVENC, VAAPI)
-
+- [Plex](https://www.plex.tv/) media and metadata
-## In Development
+- Music video libraries
-
-- [Plex](https://www.plex.tv/) media, metadata and collections
 
 ## Planned Features
 
-- [Jellyfin](https://jellyfin.org/) media, metadata and collections 
+- [Jellyfin](https://jellyfin.org/) media and metadata 
 - Run as a Windows service
 - Spots to fill unscheduled gaps
 
-## Preview
+## Screenshots
 
 ### Television Show
 
-![Television Show](docs/television-show.png)
+![Television Show](docs/images/television-show.png)
 
 ### Media Collection
 
-![Media Collection](docs/media-collection.png)
+![Media Collection](docs/images/media-collection.png)
-
-### Plex Live TV
-
-![Plex Live TV Stream](docs/plex-live-tv-stream.png)
-Sintel is © copyright Blender Foundation | durian.blender.org
-
-## Running ErsatzTV
-
-The easiest way to run ErsatzTV is with Docker:
-
-```
-docker run -d \
-  -e TZ=America/Chicago \
-  -p 8409:8409 \
-  -v /path/to/appdata/config:/root/.local/share/ersatztv \
-  -v /path/to/shared/media:/path/to/shared/media:ro \
-  --restart unless-stopped \
-  jasongdove/ersatztv
-```
-
-After running ErsatzTV for the first time, configure it by visiting the web UI at http://[address]:8409.
-
-### Software Transcoding
-
-The following docker tags are available with software transcoding:
-
-* `develop` - merges to `main` branch
-* `latest` - latest release
-
-### Hardware Transcoding
-
-The following docker tags are available with hardware-accelerated transcoding:
-
-* `develop-nvidia` - merges to `main` branch
-* `develop-vaapi` - merges to `main` branch
-* `latest-nvidia` - latest release
-* `latest-vaapi` - latest release
-
-QSV transcoding has not been tested in docker.
-
-## Development
-
-See [development documentation](docs/development.md).
 
 ## License
 

docs/index.md

@@ -0,0 +1,14 @@
+![ErsatzTV](../images/ersatztv.png)
+
+**ErsatzTV** is pre-alpha software for configuring and streaming custom live channels using your media library. The software is currently unstable and under active development.
+
+Want to join the community or have a question? Join us on [Discord](https://discord.gg/hHaJm3yGy6).
+
+Want to say thanks? Consider [sponsorship on GitHub](https://github.com/sponsors/jasongdove) or [one-time donations on PayPal](https://www.paypal.me/jasongdove).
+
+# Quick Start
+
+1. [Install ErsatzTV](user-guide/install.md)
+2. [Add Media Items](user-guide/add-media-items.md)
+3. [Create Channels](user-guide/create-channels.md)
+4. [Configure Clients](user-guide/configure-clients.md)

docs/stylesheets/extra.css

@@ -0,0 +1,14 @@
+:root {
+    --md-primary-fg-color: #121212;
+}
+
+[data-md-color-scheme="slate"] {
+    --md-default-bg-color: #272727;
+    --md-typeset-a-color: #00a0a0;
+    --md-accent-fg-color: #00c0c0;
+    --md-default-fg-color--light: #ffffff;
+    
+    --md-code-bg-color: #1f1f1f;
+    --md-footer-bg-color: #1f1f1f;
+    --md-footer-bg-color--dark: #121212;
+}

docs/user-guide/add-media-items.md

@@ -0,0 +1,82 @@
+ErsatzTV needs to know about your media items in order to create channels.
+Two library kinds are currently supported: [Local](#local-libraries) and [Plex](#plex-libraries).
+
+## Local Libraries
+
+ErsatzTV provides three local libraries, one for each supported media kind: `Movies`, `Shows` and `Music Videos`.
+
+### Metadata
+
+With local libraries, ErsatzTV will read metadata from [NFO files](https://kodi.wiki/view/NFO_files), falling back to a *minimal* amount of metadata if NFO files are not found.
+
+### Add Media Items
+
+To add media items to a local library under `Media` > `Libraries`, click the edit button for the library:
+
+![Libraries Edit Icon](../images/libraries-edit-icon.png)
+
+Then click the `Add Library Path` button and enter the path where your media files of the appropriate kind are stored:
+
+![Add Local Library Path](../images/shows-add-local-library-path.png)
+
+Finally, click `Add Local Library Path` and ErsatzTV will scan and import your media items.
+
+## Plex Libraries
+
+Plex libraries provide a way to synchronize your media (metadata) from Plex to ErsatzTV.
+This synchronization process is one-way: changes made within Plex are synchronized to ErsatzTV.
+ErsatzTV will never make any modifications to your Plex configuration or media.
+
+### Metadata
+
+With Plex libraries, Plex provides all metadata.
+
+### Add Media Items
+
+#### Sign In
+
+The add media items from Plex under `Media Sources` > `Plex`, click the `Sign in to Plex` button and sign in with your Plex account.
+
+#### Synchronize Libraries
+
+After signing in, select which libraries you would like to synchronize from Plex to ErsatzTV by clicking the `Edit Libraries` button for the desired Plex server.
+
+![Plex Edit Libraries Icon](../images/plex-media-source-edit-libaries-icon.png)
+
+In the libraries listing, click the `Synchronize` switch for all libraries you would like to synchronize from Plex to ErsatzTV, and click the `Save Changes` button to start the synchronization process.
+
+![Plex Libraries Synchronize Switch](../images/plex-libraries-synchronize-switch.png)
+
+### Path Replacements
+
+Media items are not streamed from Plex media sources. Instead, ErsatzTV will attempt to play media items from disk using the same path that Plex uses to play the media item.
+There are two ways to make this work:
+
+1. Ensure ErsatzTV has access to exactly the same shares and mounts as Plex
+2. Configure path replacements to tell ErsatzTV where it should look on its file system for a given Plex folder
+
+Option 1 is recommended as it will "just work" without any further configuration.
+
+To configure path replacements for a Plex media source, click the `Edit Path Replacements` button in the 
+
+![Plex Edit Path Replacements Icon](../images/plex-media-source-edit-path-replacements-icon.png)
+
+Click `Add Path Replacement` to add a new path replacement, and enter the `Plex Path` along with the equivalent `Local Path` for ErsatzTV.
+Click `Save Changes` after you have created all needed path replacements.
+
+![Plex Path Replacements](../images/plex-media-source-path-replacements.png)
+
+## Collections
+
+ErsatzTV does not schedule individual media items; only collections of items can be scheduled.
+To create a collection, find the media items you would like to include and select them by clicking the selection button in the top left of the poster:
+
+![Poster Selection Button](../images/poster-selection-button.png)
+
+Then, add to a collection by clicking the `Add To Collection` button at the top of the page.
+
+![Add Selection To Collection](../images/add-selection-to-collection.png)
+
+In the `Add To Collection` dialog, either select an existing collection for the items, or enter a new collection name to create a collection and add all of the selected items in a single step.
+
+![Add To Collection Dialog](../images/add-to-collection-dialog.png)

docs/user-guide/configure-clients.md

@@ -0,0 +1,113 @@
+## Required Urls
+
+For all clients, the `M3U` and/or the `XMLTV` urls are needed and can be copied from the top right of the ErsatzTV UI.
+
+![ErsatzTV M3U and XMLTV Links](../images/etv-m3u-xmltv-links.png)
+
+## Supported Clients
+
+- [Plex](#plex)
+- [Jellyfin](#jellyfin)
+- [TiviMate](#tivimate)
+- [Channels DVR Server](#channels-dvr-server)
+
+## Plex
+
+A [Plex Pass](https://www.plex.tv/plex-pass/) is required for ErsatzTV to work with Plex.
+
+### Add DVR
+
+From Plex Settings, click `Live TV & DVR` and  `Set Up Plex DVR` to add a new DVR.
+If ErsatzTV is not automatically detected
+
+  * Click to `enter its network address manually`
+  * Enter ErsatzTV's IP address and port, like `192.168.1.100:8409` (use your server IP, not necessarily 192.168.1.100)
+  * Click `Connect`
+
+![Plex DVR Manual Address](../images/plex-dvr-manual-address.png)
+
+### Add XMLTV
+
+Click `Continue` on the channel listing, then
+
+  * Click `Have an XMLTV guide on your server? Click here to use that instead.`
+  * Enter the `XMLTV` url from ErsatzTV (see [required urls](#required-urls)) and click `Continue`
+
+![Plex DVR XMLTV Guide](../images/plex-dvr-xmltv-guide.png)
+
+Make any desired changes to the channels, then click `Continue` to complete DVR setup.
+
+## Jellyfin
+
+Jellyfin requires two steps to configure Live TV:
+
+- [Add Tuner Device](#add-tuner-device)
+- [Add TV Guide Data](#add-tv-guide-data)
+
+### Add Tuner Device
+
+From the Admin Dashboard in Jellyfin, click `Live TV` and `+` to add a new tuner device:
+
+![Jellyfin Add Tuner Device](../images/jellyfin-add-tuner-device.png)
+
+For `Tuner Type` select `HD Homerun`, and for `Tuner IP Address` enter ErsatzTV's IP address and port, like `192.168.1.100:8409` (use your server IP, not necessarily 192.168.1.100).
+
+![Jellyfin Live TV Tuner Setup](../images/jellyfin-live-tv-tuner-setup.png)
+
+### Add TV Guide Data
+
+From the Admin Dashboard in Jellyfin, click `Live TV` and `+` to add a tv guide data provider and select `XMLTV`.
+
+![Jellyfin Add TV Guide Data Provider](../images/jellyfin-add-tv-guide-data-provider.png)
+
+Enter the `XMLTV` url from ErsatzTV (see [required urls](#required-urls)) and click `Save`.
+
+![Jellyfin XMLTV Settings](../images/jellyfin-xmltv-settings.png)
+
+## TiviMate
+
+### Add Playlist
+
+Start by adding a playlist under `Settings` > `Playlists` > `Add playlist`.
+The playlist type is `M3U Playlist` and the url is the `M3U` url from ErsatzTV (see [required urls](#required-urls)).
+
+![TiviMate Playlist URL](../images/tivimate-playlist-url.png)
+
+Change the playlist name if desired, and leave `TV playlist` selected.
+
+### Add EPG
+
+The EPG url should be automatically detected by TiviMate, but can be manually entered as the `XMLTV` url from ErsatzTV (see [required urls](#required-urls)).
+
+![TiviMate EPG URL](../images/tivimate-epg-url.png)
+
+## Channels DVR Server
+
+[Channels Plus](https://getchannels.com/plus/) is required for ErsatzTV to work with Channels (via Channels DVR Server).
+
+### Add Custom Channel Source
+
+In Channels DVR Server Settings, click `Add Source` and select `Custom Channels`.
+
+- Give your custom channel source a name
+- Select `MPEG-TS` as the stream format
+- Enter the `M3U` url from ErsatzTV (see [required urls](#required-urls))
+- Select `Refresh URL daily`
+- Set a stream limit if desired (not required)
+- Click `Save`
+
+![Channels Custom Channel Source](../images/channels-custom-channels-source.png)
+
+### Add Guide Data Provider
+
+In Channels DVR Settings, click the gear icon next to the ErsatzTV channel source and select `Set Provider`:
+
+![Channels Guide Data Set Provider](../images/channels-guide-data-set-provider.png)
+
+Click the drop down next to zip code and select `XMLTV > Custom URL`:
+
+![Channels XMLTV Custom URL Dropdown](../images/channels-xmltv-custom-url-dropdown.png)
+
+Enter the `XMLTV` url from ErsatzTV (see [required urls](#required-urls)) and click `Save`.
+
+![Channels XMLTV Custom URL](../images/channels-xmltv-custom-url.png)

docs/user-guide/create-channels.md

@@ -0,0 +1,79 @@
+## Create Channel
+
+Create a Channel by navigating to the `Channels` page and clicking `Add Channel`.
+
+### Channel Number
+
+Channel numbers can be whole numbers or can contain one decimal, like `500` or `500.5`.
+
+### Streaming Mode
+
+Two streaming modes are currently supported: `Transport Stream` and `HttpLiveStreaming`.
+`Transport Stream` is considered stable and is recommended for most purposes.
+`HttpLiveStreaming` is unstable and is not recommended for general use.
+
+### FFmpeg Profile
+
+FFmpeg Profiles are collections of transcoding settings that are applied to all content on a channel.
+The default FFmpeg Profile is probably "good enough" for initial testing.
+
+### Logo
+
+Channel logos can be added using the `Upload Logo` button and the logos will display in most client program guides.
+
+## Create Schedule
+
+Schedules are used to control the playback order of media items on a channel.
+Create a Schedule by navigating to the `Schedules` page, clicking `Add Schedule` and giving your schedule a name, a collection playback order, and clicking `Add Schedule` to confirm your selections.
+
+### Collection Playback Order
+
+Select the desired playback order for media items within each collection in the schedule:
+
+- `Chronological`: Items are ordered by release date, then by season and episode number.
+- `Random`: Items are randomly ordered and may contain repeats.
+- `Shuffle`: Items are randomly ordered and no item will be played a second time until every item from the collection has been played once.
+
+### Schedule Items
+
+Schedules contain an ordered list of items (collections), and will play back one or more items from each collection before advancing to the next schedule item.
+
+Edit the new schedule's items by clicking the `Edit Schedule Items` button for the schedule:
+
+![Schedules Edit Schedule Items Button](../images/schedules-edit-schedule-items.png)
+
+Add a new item to the schedule by clicking `Add Schedule Item` and configure as desired.
+
+#### Start Type
+
+Items with a `Dynamic` start type will start immediately after the preceding schedule item, while a `Fixed` start type requires a start time.
+
+#### Collection Type
+
+Schedule items can contain the following collection types:
+
+- `Collection`: Select a collection that you have created manually.
+- `Television Show`: Select an entire television show.
+- `Television Season`: Select a specific season of a television show.
+
+#### Collection
+
+Based on the selected collection type, select the desired collection.
+
+#### Playout Mode
+
+Select how you want this schedule item to behave every time it is selected for playback.
+
+- `One`: Play one media item from the collection before advancing to the next schedule item.
+- `Multiple`: Play the specified `Multiple Count` of media items from the collection before advancing to the next schedule item.
+- `Duration`: Play the maximum number of complete media items that will fit in the specified `Playout Duration` before either going offline for the remainder of the playout duration (an `Offline Tail`), or immediately advancing to the next schedule item.
+- `Flood`: Play media items from the collection either forever or until the next schedule item's start time, if one exists.
+
+Click `Save Changes` to save all changes made to the schedule's items.
+
+## Create Playout
+
+Playouts assign a schedule to a channel and individually track the ordered playback of collection items.
+If a schedule is used in multiple playouts (channels), the channels may not have the same content playing at the same time.
+
+To create a Playout, navigate to the `Playouts` page and click the `Add Playout` button. Then, select the appropriate channel and schedule, and click `Add Playout` to save.

docs/user-guide/install.md

@@ -0,0 +1,101 @@
+ErsatzTV is available as Docker images and as pre-built binary packages for Windows, MacOS and Linux. 
+
+## Docker Images
+
+<a href="https://hub.docker.com/r/jasongdove/ersatztv"><img alt="Docker Pull Count" src="https://img.shields.io/docker/pulls/jasongdove/ersatztv"></a>
+
+### Latest Release Tags
+
+Base (software transcoding): `jasongdove/ersatztv:latest`
+
+Nvidia hardware-accelerated transcoding: `jasongdove/ersatztv:latest-nvidia`
+
+VAAPI hardware-accelerated transcoding: `jasongdove/ersatztv:latest-vaapi`
+
+### Development Tags
+
+Development tags update much more frequently, but have the potential to be less stable than releases. 
+
+Base (software transcoding): `jasongdove/ersatztv:develop`
+
+Nvidia hardware-accelerated transcoding: `jasongdove/ersatztv:develop-nvidia`
+
+VAAPI hardware-accelerated transcoding: `jasongdove/ersatztv:develop-vaapi`
+
+### Docker
+
+1\. Download the latest container image
+
+```
+docker pull jasongdove/ersatztv
+```
+
+2\. Create a directory to store configuration data
+
+```
+mkdir /path/to/config
+```
+
+3\. Create and run a container
+
+```
+docker run -d \
+  --name ersatztv \
+  -e TZ=America/Chicago \
+  -p 8409:8409 \
+  -v /path/to/config:/root/.local/share/ersatztv \
+  -v /path/to/shared/media:/path/to/shared/media:ro \
+  --restart unless-stopped \
+  jasongdove/ersatztv
+```
+
+### Unraid Docker
+
+ 1. Install the Commuinity Applications plugin by pasting the following URL in the Plugins / Install Plugin section of UnRAID  
+
+```
+https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg
+```  
+
+ ![Community Applications Install](../images/unraid-install-community-apps.png)  
+2. Click on the `Apps` tab in UnRAID, search for `ersatztv`, and click the `install` button.
+
+![Search Community Applications ErsatzTV](../images/unraid-docker-install-ersatz.png)
+3. Choose an appropriate branch (Use `vaapi` for video acceleration for AMD GPUs and Intel CPUs with QuickSync, use `nvidia` for video acceleration for nVidia GPUs)
+
+![ErsatzTV Docker branches](../images/unraid-docker-ersatz-branches.png)
+	<div align="center">`VAAPI` and `nVidia` branches are for hardware acceleration. See [latest release tags](install.md#latest-release-tags)</div>
+4. Map your path to shared media
+
+![Media Mapping](../images/unraid-docker-media-map.png)
+5. <B>OPTIONAL</B> In advanced view, add extra parameters for video acceleration. **NOTE** The [nVidia-Driver plugin](https://forums.unraid.net/topic/98978-plugin-nvidia-driver/) must be installed prior to this step.
+
+![Adding video acceleration options](../images/unraid-docker-ersatz-hwtranscoding.png)
+6. Open your browser to `http://[docker-ip]:8409` (First run may take a few minutes to be available.)
+
+## Windows
+
+### Manual Installation
+
+1. Create a folder `ersatztv` at your preferred install location.
+2. Download and extract the latest version to the `ersatztv` folder.
+3. Run `ErsatzTV.exe`
+4. Open your browser to `http://[server-ip]:8409`
+
+## MacOS
+
+### Manual Installation
+
+1. Create a folder `ersatztv` at your preferred install location.
+2. Download and extract the latest version to the `ersatztv` folder.
+3. Run `ErsatzTV`
+4. Open your browser to `http://[server-ip]:8409`
+
+## Linux
+
+### Manual Installation
+
+1. Create a folder `ersatztv` at your preferred install location.
+2. Download and extract the latest version to the `ersatztv` folder.
+3. Run `ErsatzTV`
+4. Open your browser to `http://[server-ip]:8409`

mkdocs.yml

@@ -0,0 +1,33 @@
+site_name: ErsatzTV
+nav:
+  - 'Quick Start':
+    - 'Install ErsatzTV': 'user-guide/install.md'
+    - 'Add Media Items': 'user-guide/add-media-items.md'
+    - 'Create Channels': 'user-guide/create-channels.md'
+    - 'Configure Clients': 'user-guide/configure-clients.md'
+theme:
+  name: material
+  palette:
+    scheme: slate
+  logo: images/ersatztv-square-logo.png
+  favicon: images/favicon-32x32.png
+extra_css:
+  - stylesheets/extra.css
+copyright: Copyright © 2020 - 2021 Jason Dove
+extra:
+  social:
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/hHaJm3yGy6
+      name: ErsatzTV on Discord
+    - icon: fontawesome/brands/github
+      link: https://github.com/jasongdove/ErsatzTV
+      name: ErsatzTV on GitHub
+    - icon: fontawesome/regular/heart
+      link: https://github.com/sponsors/jasongdove
+      name: Sponsor on GitHub
+    - icon: fontawesome/brands/paypal
+      link: https://www.paypal.me/jasongdove
+      name: Donate on PayPal
+google_analytics:
+  - UA-193031642-1
+  - auto