From 86541ddd51468309503fad73a97f29deb89ea64c Mon Sep 17 00:00:00 2001 From: natyusha <985941+natyusha@users.noreply.github.com> Date: Tue, 15 Oct 2024 06:39:43 -0400 Subject: [PATCH] Add More Info to the Relay Utility Scripts Page - Include more config options and the entirety of Relay's readme section on the scripts. --- docs/plex/shoko-relay-utility-scripts.md | 271 +++++++++++++++-------- 1 file changed, 181 insertions(+), 90 deletions(-) diff --git a/docs/plex/shoko-relay-utility-scripts.md b/docs/plex/shoko-relay-utility-scripts.md index 005adb80..94bb692f 100644 --- a/docs/plex/shoko-relay-utility-scripts.md +++ b/docs/plex/shoko-relay-utility-scripts.md @@ -70,6 +70,26 @@ const plexConfigTableData = [ Option: 'LibraryNames', Description: `The names of any libraries which you want the scripts to interact with. **Must be formatted as a Python list** e.g. \`'LibraryNames': ['Anime Shows', 'Anime Movies'],\``, }, + { + Option: 'ExtraUsers (Optional)', + Description: `The usernames of any managed or home users to sync watched states for (watched-sync.py) **Must be formatted as a Python list** e.g. \`'ExtraUsers': ['Family'],\``, + }, + { + Option: 'DataFolder (Optional)', + Description: `The Location of your Plex [data folder](https://support.plex.tv/articles/202915258-where-is-the-plex-media-server-data-directory-located/) (collection-posters.py clean). **Requires double backslashes on windows** e.g. \`'DataFolder': '%LOCALAPPDATA%\\\\Plex Media Server',\``, + }, + { + Option: 'PostersFolder (Optional)', + Description: `The folder containing any custom collection posters (collection-posters.py). **Requires double backslashes on windows** e.g. \`'PostersFolder': 'M:\\\\Anime\\\\Posters',\``, + }, + { + Option: 'SyncAdmin', + Description: 'Whether the watched states of the Admin account should be synced (watched-sync.py)', + }, + { + Option: 'X-Plex-Token (2FA)', + Description: 'An alternate Plex authentication method for those using two-factor authentication. More info on obtaining a token [here](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/).', + }, ]; const shokoConfigColumns = [ @@ -131,9 +151,7 @@ For ease of use, adding the Scripts folder to the **[PATH](https://en.wikipedia. recommended. :::info -In depth information about each script and its functionality can be found in the Shoko -Relay [Readme](https://github.com/natyusha/ShokoRelay.bundle?tab=readme-ov-file#scripts). These scripts also function -with Shoko Metadata. +These scripts also function with Shoko Metadata (thought it is not supported). ::: ## Prerequisites @@ -187,102 +205,175 @@ the readme for all of the commands. ### AnimeThemes -Run in a terminal `animethemes.py` with the working directory set to a folder containing an anime series. If the anime -has been matched by Shoko Server it will grab the anidbID and use that to match with an AnimeThemes anime entry. -Append the arguments "slug" / "offset" `animethemes.py slug offset` in order to specify which opening or ending to -download. - -- slug: an optional identifier which must be the first argument and is formatted as "op", "ed", "op2", "ed2" and so on -- offset: an optional single digit number which must be the second argument if the slug is provided - -Append the argument "play" to the commands above to run in "Preview" mode. - -- play: for force enabling FFplay and disabling Theme.mp3 generation, must be the last or sole argument and is simply - entered as "play" - -Append the argument "batch" `animethemes.py batch` when running the script on multiple folders at a time. - -- batch: must be the sole argument and is simply entered as "batch" - -###### Example Commands: - -:::info -Using bash / cmd respectively and assuming that both the script and FFmpeg can be called directly from PATH. +- This script uses the Shoko and [AnimeThemes](https://animethemes.moe/) APIs to find the OP/ED for a series and convert it into a Theme.mp3 file which will play when viewing the series in Plex. +- The default themes grabbed by Plex are limited to 30 seconds long and are completely missing for a massive amount of anime making this a great upgrade to local metadata. + +:::details Additional Information +**Requirements:** +- Python 3.7+, Requests Library (pip install requests), FFmpeg, Shoko Server + +**Preferences:** +- Before doing anything with this script you must enter your Shoko credentials into `config.py`. +- To allow Theme.mp3 files to be used by Plex you must also enable "Local Media Assets" for the libraries that have your Anime in it. + - The "Play Theme Music" option also has to be enabled in the settings for the Plex client. + +**Usage:** +- Run in a terminal `animethemes.py` with the working directory set to a folder containing an anime series. +- If the anime has been matched by Shoko Server it will grab the anidbID and use that to match with an AnimeThemes anime entry. + +**Behaviour:** +- By default this script will download the first OP (or ED if there is none) for the given series. +- If "FFplay_Enabled" is set to True in `config.py` the song will begin playing in the background which helps with picking the correct theme. +- FFmpeg will then encode it as a 320kbps mp3 and save it as Theme.mp3 in the anime folder. +- FFmpeg will also apply the following metadata: + - Title (with TV Size or not) + - Artist (if available) + - Album (as source anime) + - Subtitle (as OP/ED number + the version if there are multiple) +- If you want a different OP/ED than the default simply supply the AnimeThemes slug as an argument. +- For the rare cases where there are multiple anime mapped to the same anidbID on AnimeThemes you can add an offset as an argument to select the next matched entry. +- When running this on multiple folders at once adding the "batch" argument is recommended. This disables audio playback and skips folders already containing a Theme.mp3 file. + - If "BatchOverwrite" is set to true in `config.py` the batch argument will instead overwrite any existing Theme.mp3 files. + +**Arguments:** +- Append the arguments "slug" / "offset" `animethemes.py slug offset` in order to specify which opening or ending to download. + - slug: an optional identifier which must be the first argument and is formatted as "op", "ed", "op2", "ed2" and so on + - offset: an optional single digit number which must be the second argument if the slug is provided +- Append the argument "play" to the commands above to run in "Preview" mode. + - play: for force enabling FFplay and disabling Theme.mp3 generation, must be the last or sole argument and is simply entered as "play" +- Append the argument "batch" `animethemes.py batch` when running the script on multiple folders at a time. + - batch: must be the sole argument and is simply entered as "batch" + +**Example Commands:** +> :pencil2: **Note** +> Using bash / cmd respectively and assuming that both the script and FFmpeg can be called directly from the PATH. +- Library Batch Processing + - `for d in "/PathToAnime/"*/; do cd "$d" && animethemes.py batch; done` + - `for /d %d in ("X:\PathToAnime\*") do cd /d %d && animethemes.py batch` +- Fix "Mushoku Tensei II: Isekai Ittara Honki Dasu" Matching to Episode 0 (offset to the next animethemes match) + - `cd "/PathToMushokuTenseiII"; animethemes.py 1` + - `cd /d "X:\PathToMushokuTenseiII" && animethemes.py 1` +- Same as above but download the second ending instead of the default OP + - `cd "/PathToMushokuTenseiII"; animethemes.py ed2 1` + - `cd /d "X:\PathToMushokuTenseiII" && animethemes.py ed2 1` +- Download the 9th Opening of Bleach + - `cd "/PathToBleach"; animethemes.py op9` + - `cd /d "X:\PathToBleach" && animethemes.py op9` +- Preview the 9th Opening of Bleach + - `cd "/PathToBleach"; animethemes.py op9 play` + - `cd /d "X:\PathToBleach" && animethemes.py op9 play` ::: -Library Batch Processing: - -- `for d in "/PathToAnime/"*/; do cd "$d" && animethemes.py batch; done` -- `for /d %d in ("X:\PathToAnime\*") do cd /d %d && animethemes.py batch` - -Fix "Mushoku Tensei II: Isekai Ittara Honki Dasu" Matching to Episode 0 (offset to the next animethemes match): - -- `cd "/PathToMushokuTenseiII"; animethemes.py 1` -- `cd /d "X:\PathToMushokuTenseiII" && animethemes.py 1` - -Same as above but download the second ending instead of the default OP: - -- `cd "/PathToMushokuTenseiII"; animethemes.py ed2 1` -- `cd /d "X:\PathToMushokuTenseiII" && animethemes.py ed2 1` - -Download the 9th Opening of Bleach: - -- `cd "/PathToBleach"; animethemes.py op9` -- `cd /d "X:\PathToBleach" && animethemes.py op9` - -Preview the 9th Opening of Bleach - -- `cd "/PathToBleach"; animethemes.py op9 play` -- `cd /d "X:\PathToBleach" && animethemes.py op9 play` - ### Collection-Posters -Run in a terminal `collection-posters.py` to set Plex collection posters to user provided ones or Shoko's. - -- Any Posters in the "PostersFolder" must have the same name as their respective collection in Plex. -- The following characters must be stripped from the filenames: \ / : * ? " < > | -- The accepted file extensions are: bmp / gif / jpe / jpeg / jpg / png / tbn / tif / tiff / webp - -Append the argument "clean" `collection-posters.py clean` if you want to remove old collection posters instead. - -- This works by deleting everything but the newest custom poster for all collections. +- This script uses the Python-PlexAPI and Shoko Server to apply posters to the collections in Plex. +- It will look for posters in a user defined folder and if none are found take the default poster from the corresponding Shoko group. + +:::details Additional Information +**Requirements:** + - Python 3.7+, Python-PlexAPI (pip install plexapi), Requests Library (pip install requests), Plex, Shoko Relay, Shoko Server + +**Preferences:** +- Before doing anything with this script you must enter your Plex and Shoko Server credentials into `config.py`. +- If your anime is split across multiple libraries they can all be added in a python list under "LibraryNames". + - It must be a list to work e.g. `'LibraryNames': ['Anime Shows', 'Anime Movies']` +- The Plex "PostersFolder" and "DataFolder" settings require double backslashes on windows e.g. `'PostersFolder': 'M:\\Anime\\Posters',`. + - The "DataFolder" setting is the base [Plex Media Server Data Directory](https://support.plex.tv/articles/202915258-where-is-the-plex-media-server-data-directory-located/) (where the Metadata folder is located). + - The "PostersFolder" setting is the folder containing any custom collection posters. + +**Usage:** +- Run in a terminal `collection-posters.py` to set Plex collection posters to user provided ones or Shoko's. + - Any Posters in the "PostersFolder" must have the same name as their respective collection in Plex. + - The following characters must be stripped from the filenames: \ / : * ? " < > | + - The accepted file extensions are: bmp / gif / jpe / jpeg / jpg / png / tbn / tif / tiff / webp +- Append the argument "clean" `collection-posters.py clean` if you want to remove old collection posters instead. + - This works by deleting everything but the newest custom poster for all collections. +::: ### Force-Metadata -Run in a terminal `force-metadata.py` to remove empty collections, normalize collection sort titles, rename negative -seasons and add original titles in Plex. Append the argument "full" `force-metadata.py full` if you want to do a -time-consuming full metadata clean up. - -:::warning -In "full" mode you must wait until the Plex activity queue is fully completed before advancing to the next step (with -the enter key) or this will not function correctly. - -- You can tell if Plex is done by looking at the library in the desktop/web client or checking the logs in your "PMS - Plugin Logs" folder for activity. - -- This may take a significant amount of time to complete with a large library so it is recommended to run the first step - overnight. +- This script uses the Python-PlexAPI to force all metadata in your anime library to update to Shoko's bypassing Plex's caching or other issues. +- Any unused posters or empty collections will be removed from your library automatically while also updating negative season names, collection sort titles and original titles. +- After making sweeping changes to the metadata in Shoko (like collections or title languages) this is a great way to ensure everything updates correctly in Plex. + +:::details Additional Information +**Requirements:** +- Python 3.7+, Python-PlexAPI (pip install plexapi), Plex, Shoko Relay, Shoko Server + +**Preferences:** +- Before doing anything with this script you must enter your Plex credentials into `config.py`. +- If your anime is split across multiple libraries they can all be added in a python list under Plex "LibraryNames". + - It must be a list to work e.g. `'LibraryNames': ['Anime Shows', 'Anime Movies']` + +**Usage:** +- Run in a terminal `force-metadata.py` to remove empty collections, normalise collection sort titles, rename negative seasons and add original titles in Plex. +- Append the argument "full" `force-metadata.py full` if you want to do a time consuming full metadata clean up. + +> :warning: **Important** +> In "full" mode you must wait until the Plex activity queue is fully completed before advancing to the next step (with the enter key) or this will not function correctly. +> - You can tell if Plex is done by looking at the library in the desktop/web client or checking the logs in your "PMS Plugin Logs" folder for activity. +> - This may take a significant amount of time to complete with a large library so it is recommended to run the first step overnight. + +**Behaviour:** +- This script will ignore locked fields/posters assuming that the user wants to keep them intact. +- Manually merged series will not be split apart and may need to be handled manually to correctly refresh their metadata. +- If the main title of an anime was changed on AniDB or overridden in Shoko after it was first scanned into Plex it might fail to match using this method. + - In these cases the original title will be output to the console for the user to fix with a Plex dance or manual match. +- Video preview thumbnails and watched states are maintained with this script (unless an anime encounters the above naming issue). +- The "Original Title" for all series will be set using info Shoko Relay added to the "Sort Title" (if available). +- Negative seasons like "Season -1" which contain Credits, Trailers, Parodies etc. will have their names updated to reflect their contents. +- The "Sort Title" for all collections will be set to match the current title to avoid Plex's custom sorting rules e.g. ignoring "The" or "A" +- All Smart Collections are ignored as they are not managed by Shoko Relay ::: ### Rescan-Recent - -Run in a terminal `rescan-recent.py` to trigger a Plex rescan of the 5 most recently added series in Shoko. Change the -number of recently added series (from 1-99) to rescan with an argument when 5 isn't enough: - -- `rescan-recent.py 20` would rescan the 20 most recently added series - -Append the argument "import" `rescan-recent.py import` if you want to force shoko to import unrecognized files instead. +- This is mostly used for quickly adding currently airing series to Plex that were unrecognized when initially imported into Shoko. +- Once the files are recognized running this script will trigger a rescan in Plex for any series that they are attached to. +- This requires Plex's partial scanning (or an alternative) to be enabled. + +:::details Additional Information +**Requirements:** +- Python 3.7+, Requests Library (pip install requests), Plex, Shoko Server + +**Preferences:** +- Before doing anything with this script you must enter your Shoko Server credentials into `config.py`. +- The Path Remapping section can be configured when running the scripts from a location where the paths differ from Shoko's. + +**Usage:** +- Run in a terminal `rescan-recent.py` to trigger a Plex rescan of the 5 most recently added series in Shoko. +- Change the number of recently added series (from 1-99) to rescan with an argument when 5 isn't enough: + - `rescan-recent.py 20` would rescan the 20 most recently added series +- Append the argument "import" `rescan-recent.py import` if you want to force shoko to import unrecognized files instead. +::: ### Watched-Sync - -Run in a terminal `watched-sync.py` to sync watched states from Plex to Shoko. Append a relative date suffix as an -argument to narrow down the time frame and speed up the process: - -- `watched-sync.py 2w` would return results from the last 2 weeks -- `watched-sync.py 3d` would return results from the last 3 days - -The full list of suffixes (from 1-999) are: m=minutes, h=hours, d=days, w=weeks, mon=months, y=years - -Append the argument "import" `watched-sync.py import` if you want to sync watched states from Shoko to Plex instead. - -- The script will ask for (Y/N) confirmation for each Plex user that has been configured. +- This script uses the Python-PlexAPI and Shoko Server to sync watched states from Plex to Shoko or Shoko to Plex. +- If something is marked as watched in Plex it will also be marked as watched in Shoko and AniDB. +- This was created due to various issues with Plex and Shoko's built in watched status syncing. + - Primarily, the webhook for syncing requires Plex Pass and does not account for things manually marked as watched. + +:::details Additional Information +**Requirements:** +- Python 3.7+, Python-PlexAPI (pip install plexapi), Requests Library (pip install requests), Plex, Shoko Relay, Shoko Server + +**Preferences:** +- Before doing anything with this script you must enter your Plex and Shoko Server credentials into `config.py`. +- If your anime is split across multiple libraries they can all be added in a python list under Plex "LibraryNames". + - It must be a list to work e.g. `'LibraryNames': ['Anime Shows', 'Anime Movies']` +- If you want to track watched states from managed/home accounts on your Plex server you can add them to Plex "ExtraUsers" following the same list format as above. + - Leave it as "None" otherwise. +- If you don't want to track watched states from your Plex Server's Admin account set "SyncAdmin" to "False". + - Leave it as "True" otherwise. + +**Usage:** +- Run in a terminal `watched-sync.py` to sync watched states from Plex to Shoko. +- Append a relative date suffix as an argument to narrow down the time frame and speed up the process: + - `watched-sync.py 2w` would return results from the last 2 weeks + - `watched-sync.py 3d` would return results from the last 3 days +- The full list of suffixes (from 1-999) are: m=minutes, h=hours, d=days, w=weeks, mon=months, y=years +- Append the argument "import" `watched-sync.py import` if you want to sync watched states from Shoko to Plex instead. + - The script will ask for (Y/N) confirmation for each Plex user that has been configured. + +**Behaviour:** +- Due to the potential for losing a huge amount of data removing watch states has been omitted from this script. +:::