update user functionality

mkdocs/docs/channels.md

@@ -50,11 +50,20 @@ If available, you can find the channel description and channel tags here.
 
 The channel customize form gives options to change settings on a per channel basis. Any configurations here will overwrite your configurations from the [settings](settings/application.md) page.
 
-- **Download Format**: Overwrite the download quality for videos from this channel.
+#### Download Format
-- **Auto Delete**: Automatically delete watched videos from this channel after selected days.
+Overwrite the download quality for videos from this channel.
-- **Index Playlists**: Automatically add all Playlists with at least a video downloaded to your index. Only do this for channels where you care about playlists as this will slow down indexing new videos because each video will need to check if it belongs to each indexed playlist. This works best if a channel creates playlists containing videos from that channel. Also see [subscribing to Playlist](playlists.md/#playlist-overview).
+
-- **SponsorBlock**: Using [SponsorBlock](https://sponsor.ajay.app/) to get and skip sponsored content. Customize per channel: You can *disable* or *enable* SponsorBlock for certain channels only to overwrite the behavior set on the [settings](settings/application.md) page. Selecting *unset* will remove the overwrite and your setting will fall back to the default on the settings page.
+#### Auto Delete
-- **Page Size**: This will overwrite the page size per channel as described in the [settings](settings/application.md#subscriptions). Setting a value to `0` (zero) you can deactivate shorts on this channel, for example.
+Automatically delete watched videos from this channel after selected days.
+
+#### Index Playlists
+Automatically add all Playlists with at least a video downloaded to your index. Only do this for channels where you care about playlists as this will slow down indexing new videos because each video will need to check if it belongs to each indexed playlist. This works best if a channel creates playlists containing videos from that channel. Also see [subscribing to Playlist](playlists.md/#playlist-overview).
+
+#### SponsorBlock
+Using [SponsorBlock](https://sponsor.ajay.app/) to get and skip sponsored content. Customize per channel: You can *disable* or *enable* SponsorBlock for certain channels only to overwrite the behavior set on the [settings](settings/application.md) page. Selecting *reset* will remove the overwrite and your setting will fall back to the default on the settings page.
+
+#### Page Size Overrides
+This will overwrite the page size per channel as described in the [settings](settings/application.md#subscriptions). By setting a value to `0` (zero) you can effectively deactivate shorts on this channel, for example.
 
 ### Downloads
 If you have any videos from this channel pending in the download queue, a *Downloads* link will show, bringing you directly to the [downloads](downloads.md) page, filtering the list by the selected channel.

mkdocs/docs/faq.md

@@ -38,7 +38,7 @@ This project is natively a container-based Docker application: There are multipl
 Docker is the only supported installation method. If you don't have any experience with Docker, consider investing the time to learn this very useful technology. Alternatively, you can find user provided installation instructions for Podman [here](installation/podman.md).
 
 ## How do I install this on Windows?
-The only supported methodology is through Docker on Windows. We don't currently have installation instructions provided, however it has been reported that some users have been successful in getting it to work with modification of the base `docker-compose.yml`. Try following the [Docker Compose](installation/docker-compose.md) instructions.
+The only supported methodology is through Docker on Windows. We don't currently have dedicated installation instructions for Windows, however users have reported that they have been successful in getting it to work using docker and docker-compose through WSL (Windows Subsystem for Linux) with modification of the base `docker-compose.yml`. Try following the [Docker Compose](installation/docker-compose.md) instructions.
 
 <!-- This question uses &lt; for `<` and &gt; for `>` because Makedocs doesn't handle the characters properly. -->
 ## Where is the .exe/.rpm/.pkg/.msi/&lt;insert installer here&gt;?
@@ -69,7 +69,7 @@ This project doesn't make any recommendations: Some people prefer to convert the
 There are too many variations of that problem to be implemented in this project, use any of the various solutions out there that fits your needs.
 
 ## Why is there no flexible naming structure?
-Unlike other similar projects, **Tube Archivist** needs to keep track of its media files indefinitely while everything can change: Channel names and aliases and titles regularly change over time. Previous attempts failed at handling that properly, breaking things and causing other unexpected behavior.
+Unlike other similar projects, **Tube Archivist** needs to keep track of its media files indefinitely while everything can change: Channel names and aliases and titles regularly change over time. Previous attempts failed at handling that properly, causing data loss in some edge cases and breaking things and causing other unexpected behavior.
 
 This project tries to be compatible with as many filesystem/OS variations out there as possible. Using channel names and titles to build file paths that can be any Unicode character is a flawed and highly error prone approach of doing that. There is always a filesystem/OS out there that proves to be incompatible with how something is named.
 

mkdocs/docs/settings/application.md

@@ -5,46 +5,79 @@ description: Configure this application.
 # Application Settings Page
 Accessible at `/settings/application/` of your **Tube Archivist** instance, this page holds all of the general application configuration settings (minus configuration of the [scheduler](scheduling.md)).
 
-!!! tip "Saving Configurations"
-    Click on **Update Application Configurations** at the bottom of the page to apply your configurations.
-
 ## Subscriptions
-Settings related to the channel management. Disable shorts or streams by setting their page size to 0 (zero).
+Settings related to the channel management. Disable shorts or streams by setting their page size to 0 (zero). Can also be configured on a [per channel basis](../channels.md#page-size-overrides).
 
-- **Channel Page Size**: Defines how many pages will get analyzed by **Tube Archivist** each time you click on *Rescan Subscriptions*. The default page size used by yt-dlp is **50**, which is also the recommended value to set here. Any value higher will slow down the rescan process, for example if you set the value to 51, that means yt-dlp will have to go through 2 pages of results instead of 1 and by that doubling the time that process takes. *Cannot be set to 0.*
+Defines how many pages will get analyzed by **Tube Archivist** each time you click on *Rescan Subscriptions*. The default page size used by yt-dlp is **50**, which is also the recommended value to set here. Any value higher will slow down the rescan process, for example if you set the value to 51, that means yt-dlp will have to go through 2 pages of results instead of 1 and by that doubling the time that process takes.
-- **Live Page Size**: Same as above, but for a channel's live streams. *Disable by setting to 0.*
+
-- **Shorts page Size**: Same as above, but for a channel's shorts videos. *Disable by setting to 0.*
+Also see the FAQ [Why does subscribing to a channel not download the complete channel?](../faq.md#why-does-subscribing-to-a-channel-not-download-the-complete-channel)
-- **Auto Start**: This will prioritize and automatically start downloading videos from your subscriptions over regular videos added to the download queue.
+
+### Video Page Size
+Regular videos off a channel.
+
+### Live Page Size
+Same as above, but for a channel's live streams. *Disable by setting to 0.*
+
+### Shorts page Size
+Same as above, but for a channel's shorts videos. *Disable by setting to 0.*
+
+### Auto Start
+This will prioritize and automatically start downloading videos from your subscriptions over regular videos added to the download queue.
 
 ## Downloads
 Settings related to the download process.
 
-- **Download Speed Limit**: Set your download speed limit in KB/s. This will pass the option `--limit-rate` to yt-dlp.
+### Download Speed Limit
-- **Throttled Rate Limit**: Restart download if the download speed drops below this value in KB/s. This will pass the option `--throttled-rate` to yt-dlp. Using this option might have a negative effect if you have an unstable or slow internet connection.
+Set your download speed limit in KB/s. This will pass the option `--limit-rate` to yt-dlp.
-- **Sleep Interval**: Time in seconds to sleep between requests to YouTube. It's a good idea to set this to **3** seconds. Might be necessary to avoid throttling.
+
-- **Auto Delete Watched Videos**: Automatically delete videos marked as watched after selected days. If activated, checks your videos after download task is finished. Auto deleted videos get marked as [ignored](../downloads.md#the-download-queue) and won't get added again in future rescans.
+### Throttled Rate Limit
+Restart download if the download speed drops below this value in KB/s. This will pass the option `--throttled-rate` to yt-dlp. Using this option might have a negative effect if you have an unstable or slow internet connection.
+
+### Sleep Interval
+Time in seconds to sleep between repeated requests to YouTube. It is recommended to set this to at least **10** seconds to avoid throtteling and getting blocked. The value set will be applied with a random variation of +/- 50%, e.g. a sleep interval of 10 seconds, will delay requests by between 5 and 15 seconds. This is to mimic regular user traffic.
+
+### Auto Delete Watched Videos
+Automatically delete videos marked as watched after selected days. If activated, checks your videos after download task is finished. Auto deleted videos get marked as [ignored](../downloads.md#the-download-queue) and won't get added again in future rescans.
 
 ## Download Format
 Additional settings passed to yt-dlp.
 
-- **Format**: This controls which streams get downloaded and is equivalent to passing `--format` to yt-dlp. Use one of the recommended configurations or review the documentation for [yt-dlp](https://github.com/yt-dlp/yt-dlp#format-selection). Please note: The option `--merge-output-format mp4` is automatically passed to yt-dlp to guarantee browser compatibility. Similar to that, `--check-formats` is passed as well to check that the selected formats are actually downloadable.
+### Format
-- **Format Sort**: This allows you to change how yt-dlp sorts formats by passing `--format-sort` to yt-dlp. Refer to the [documentation](https://github.com/yt-dlp/yt-dlp#sorting-formats) to see what you can pass here. Be aware that some codecs might not be compatible with your browser of choice.
+This controls which streams get downloaded and is equivalent to passing `--format` to yt-dlp. Use one of the recommended configurations or review the documentation for [yt-dlp](https://github.com/yt-dlp/yt-dlp#format-selection). Please note: The option `--merge-output-format mp4` is automatically passed to yt-dlp to guarantee browser compatibility. Similar to that, `--check-formats` is passed as well to check that the selected formats are actually downloadable.
-- **Extractor Language**: Some channels provide translated video titles and descriptions. Add the two letter ISO language code to set your prefered default language. This will only have an effect if the uploader adds translations. Not all language codes are supported, see the [documentation](https://github.com/yt-dlp/yt-dlp#youtube) (the `lang` section) for more details.
+
-- **Embed Metadata**: This saves the available tags directly into the media file by passing `--embed-metadata` to yt-dlp.
+### Format Sort
-- **Embed Thumbnail**: This saves the thumbnail into the media file by passing `--embed-thumbnail` to yt-dlp.
+This allows you to change how yt-dlp sorts formats by passing `--format-sort` to yt-dlp. Refer to the [documentation](https://github.com/yt-dlp/yt-dlp#sorting-formats) to see what you can pass here. Be aware that some codecs might not be compatible with your browser of choice.
+
+### Extractor Language
+Some channels provide translated video titles and descriptions. Add the two letter ISO language code to set your prefered default language. This will only have an effect if the uploader adds translations. Not all language codes are supported, see the [documentation](https://github.com/yt-dlp/yt-dlp#youtube) (the `lang` section) for more details.
+
+### Embed Metadata
+This saves the available tags directly into the media file by passing `--embed-metadata` to yt-dlp.
+
+### Embed Thumbnail
+This saves the thumbnail into the media file by passing `--embed-thumbnail` to yt-dlp.
 
 ## Subtitles
 
-- **Download Setting**: Select the subtitle language you like to download. Add a comma separated list for multiple languages. For Chinese you must specify `zh-Hans` or `zh-Hant`, specifying "zh" is invalid, otherwise the subtitle won't download successfully.
+### Subtitle Language
-- **Source Settings**: User created subtitles are provided from the uploader and are usually the video script. Auto generated is from YouTube. The quality varies, particularly for auto translated tracks.
+Select the subtitle language you like to download. Add a comma separated list for multiple languages. For Chinese you must specify `zh-Hans` or `zh-Hant`, specifying "zh" is invalid, otherwise the subtitle won't download successfully.
-- **Index Settings**: Enabling subtitle indexing will add the lines to Elasticsearch and will make subtitles searchable. This will increase the index size and is not recommended on low-end hardware.
+
+### Enable Auto Generated
+This will fallback to from YouTube auto generated subtitles if subtitles from the uploader are not available. Auto generated subtitles are usually less accurate, particularly for auto translated tracks.
+
+### Enable Index
+Enabling subtitle indexing will add the lines to Elasticsearch and will make subtitles searchable. This will increase the index size and is not recommended on low-end hardware.
 
 ## Comments
 
-- **Download and index comments**: Set your configuration for downloading and indexing comments. This takes the same values as documented in the `max_comments` section for the youtube extractor of [yt-dlp](https://github.com/yt-dlp/yt-dlp#youtube). Add, without spaces, between the four different fields: *max-comments,max-parents,max-replies,max-replies-per-thread*. Example:
+### Index Comments
+Set your configuration for downloading and indexing comments. This takes the same values as documented in the `max_comments` section for the youtube extractor of [yt-dlp](https://github.com/yt-dlp/yt-dlp#youtube). Add, without spaces, between the four different fields: *max-comments,max-parents,max-replies,max-replies-per-thread*. Example:
     - `all,100,all,30`: Get 100 max-parents and 30 max-replies-per-thread.
     - `1000,all,all,50`: Get a total of 1000 comments over all, 50 replies per thread.
-- **Comment sort method**: Change sort method between *top* or *new*. The default is *top*, as decided by YouTube.
+
+### Comment sort method
+Change sort method between *top* or *new*. The default is *top*, as decided by YouTube.
+
 - The [Refresh Metadata](scheduling.md#refresh-metadata) background task will get comments from your already archived videos, spreading the requests out over time.
 
 Archiving comments is slow as only a few comments get returned per request with yt-dlp. Choose your configuration above wisely. Tube Archivist will download comments after the download queue finishes. Your videos will already be available while the comments are getting downloaded.
@@ -62,11 +95,12 @@ Cookies are used to store your session and contain your access token to your Goo
 ### Auto import
 Easiest way to import your cookie is to use the **Tube Archivist Companion** [browser extension](https://github.com/tubearchivist/browser-extension) for Firefox and Chrome.
 
-### Manual import
+### Manual Update
-Alternatively, you can also manually import your cookie into Tube Archivist. Export your cookie as a *Netscape* formatted text file, name it *cookies.google.txt* and put it into the *cache/import* folder. After that you can enable the option on the settings page and your cookie file will get imported.
+Alternatively, you can also manually import your cookie into Tube Archivist. Export your cookie as a *Netscape* formatted text file and paste the content into the text field.
 
 - There are various tools out there that allow you to export cookies from your browser. This project doesn't make any specific recommendations.
 - Once imported, a **Validate Cookie File** button will show, where you can confirm if your cookie is working or not.
+- A cookie is considered as _valid_ if yt-dlp is able to access your private [Liked Videos](https://www.youtube.com/playlist?list=LL) playlist.
 
 ### Use your cookie
 Once imported, in addition to the advantages above, your [Watch Later](https://www.youtube.com/playlist?list=WL) and [Liked Videos](https://www.youtube.com/playlist?list=LL) playlists become a regularly accessible playlist that you can download and subscribe to like any other [playlist](../playlists.md).
@@ -74,12 +108,21 @@ Once imported, in addition to the advantages above, your [Watch Later](https://w
 ### Limitation
 There is only one cookie per Tube Archivist instance. This will be shared between all users.
 
+## PO Token
+Also known as _proof of origin token_, this is a token required in some cases by YT to validate the requests. See the wiki on the yt-dlp repo with more info, particularly the [PO Token Guide](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide) page.
+
 ## Integrations
 All third party integrations of **Tube Archivist** will **always** be *opt in*.
 
-- **API**: Your access token for the **Tube Archivist** API.
+### API Token
-- **returnyoutubedislike.com**: This will return dislikes and average ratings for each video by integrating with the API from [returnyoutubedislike.com](https://www.returnyoutubedislike.com/).
+Your access token for the **Tube Archivist** API.
-- **SponsorBlock**: Using [SponsorBlock](https://sponsor.ajay.app/) to retrieve timestamps for, and skip, sponsored content. If a video doesn't have timestamps, or has unlocked timestamps, use the browser addon to contribute to this excellent project. Can also be activated and deactivated on a per [channel overwrite](../channels.md#about).
+
+### ReturnYoutubeDislike
+
+This will return dislikes and average ratings for each video by integrating with the API from [returnyoutubedislike.com](https://www.returnyoutubedislike.com/).
+
+### SponsorBlock
+Using [SponsorBlock](https://sponsor.ajay.app/) to retrieve timestamps for, and skip, sponsored content. If a video doesn't have timestamps, or has unlocked timestamps, use the browser addon to contribute to this excellent project. Can also be activated and deactivated on a per [channel overwrite](../channels.md#about).
 
 ## Snapshots
 !!! info
@@ -89,6 +132,3 @@ System snapshots will automatically make daily snapshots of the Elasticsearch in
 
 - **Create snapshot now**: Will start the snapshot process now and outside of the regular daily schedule.
 - **Restore**: Restore your index to that point in time. Select one of the available snapshots to restore from.
-
-!!! tip "Saving Configurations"
-    Click on **Update Application Configurations** at the bottom of the page to apply your configurations.

mkdocs/docs/settings/user.md

@@ -12,3 +12,6 @@ Switch between the "easy on the eyes" dark theme and the "burning" bright theme.
 
 ## Archive View
 - **Page Size**: Defines how many results get displayed on each page. This value is used for all archive views.
+
+## Show Help Text
+Activating that will show helpful explanations, sometimes with examples through the interface. Untoggle that to hide that if you are familiar with this project and want to _unclutter_ the interface.

mkdocs/docs/urls.md

@@ -21,6 +21,7 @@ Urls can have several forms:
 | Watch URL | `https://www.youtube.com/watch?v=2tdiKTSdE9Y` | Regular URLs you will see while browsing YouTube, with the path */watch* and a *v* parameter |
 | Share URL | `https://youtu.be/2tdiKTSdE9Y` | Link you will get when you click on *share* on a video |
 | Shorts URL | `https://www.youtube.com/shorts/U80grnZJm_8` | Video links for YouTube shorts |
+| Live URL | `https://www.youtube.com/live/ix5XSbY8Zo4` | Video live stream URL |
 
 ## Channel
 A channel ID is **24** characters long, e.g. `UCBa659QWEk1AI4Tg--mrJ2A`.