Files

Abdulmhsen B. A. A f77967dc92 Fixed FAQ.md text

2022-05-29 03:53:25 +03:00

11 KiB

Raw Blame History

FAQ

Q: How to update play state for newly added media backend without overwriting my current play state?

First, add the media backend and when asked, answer n for allow import from this server. when you finish, run the following command:

$ docker exec -ti watchstate console state:export -vv --ignore-date --force-full --servers-filter [SERVER_NAME]

this command will force export your current local play state to the selected media backend. If the operation is successful you can then enable the import feature if you want.

Q: Is there support for Multi-user setup?

No, The tool is designed to work for single user. However, It's possible to run container for each user.

Note: for Plex managed users run the following command to extract each managed user token.

$ docker exec -ti console servers:remote --list-users-with-tokens -- my_plex_1

For jellyfin/emby, you can use same api-token and just replace the userId.

Q: Sometimes newly added episodes or movies don't make it to webhook server?

As stated in webhook limitation section sometimes media backends don't make it easy to receive those events, as such, to complement webhooks, its good idea enable the scheduled tasks of import/export and let them run once in a while to remap the data.

Q: Can this tool run without docker?

Yes, if you have the required PHP version and the needed extensions. to run this tool you need the following php8.1, and php8.1-fpm and the following extensions php8.1-pdo, php8.1-mbstring, php8.1-ctype, php8.1-curl, php8.1-sqlite3 and composer. once you have the required runtime dependencies, for first time run:

cd ~/watchstate
composer install --optimize-autoloader

after that you can start using the tool via this command.

$ php console

The app should save your data into ./var directory. If you want to change the directory you can export the environment variable WS_DATA_PATH for console and browser. you can add a file called .env in main tool directory with the environment variables. take look at the files inside docker/files directory to know how to run the scheduled tasks and ofc if you want a webhook support you would need a frontend proxy for php8.1-fpm like nginx, caddy or apache.

Q: Some records keep getting updated even when the state did not change?

This most likely means your media backends have conflicting external ids for the reported items, and thus triggering an update as the tool see different external ids on each event from the backends. In our testing we noticed that at least few hundred records in thetvdb that get reported by plex have incorrect imdb external id, which in turns conflicts sometimes with jellyfin/emby there is nothing we can do beside have the problematic records reported to thetvdb site mods to fix their db entries.

Q: I keep on seeing "Ignoring 'XXX'. No valid/supported external ids." in logs?

This most likely means that the item is not matched in your media backend

jellyfin/emby: Edit metadata and make sure there are external ids listed in the metadata.
For plex click the (...), and click Fix match. after that refresh metadata.

For episodes, we support both external ids like movies and relative unique ids, To make episodes sync work at least one of the following conditions has to be met:

The episode should have external ids.
The series should have external ids, to make relative unique id works.

Q: I enabled strict user match to allow only my user to update the play state, and now webhook requests are failing to be processed?

For Jellyfin backend

If this relates to jellyfin backend, then please make sure you have selected "Send All Properties (ignores template)".

For Plex backend

if your account is the admin account then update the user to 1 by running the following command, just change the [SERVER_NAME] to your server config name.

$ docker exec -ti watchstate console servers:edit --key user --set 1 -- [SERVER_NAME]

Q: Does this tool require webhooks to work?

No, You can use the task scheduler or on demand sync if you want. However, we recommend the webhook method as it's the most efficient method to update play state.

Q: When i use jellyfin, i sometimes see double events?

This most likely a bug in the plugin jf-webhook #113, Just reload the page make sure there is only one added watchstate endpoint.

Q: I keep on seeing "..., entity state is tainted." what does that means?

Tainted events are events that are not used to update the play state, but are interesting enough for us to keep around for other benefits like updating the external ids mapping for movies/episodes. It's normal do not worry about it.

Q: How can I see my play state list?

$ docker exec -ti watchstate console db:list

This command will give you access to see the database entries. by default, it will show the last 20 events, however you can run the same command with [-h, --help] to see more options to extend the list or to filter the results.

Q: Can I ignore specific libraries from being processed?

Yes, First run the following command

$ docker exec -ti watchstate console servers:remote --list-libraries -- [SERVER_NAME]

it should show you list of given server libraries, you are mainly interested in the ID column. take note of the library id, after that run the following command to ignore the libraries. The options.ignore accepts comma seperated list of ids to ignore.

$ docker exec -ti watchstate console servers:edit --key options.ignore --set 'id1,id2,id3' -- [SERVER_NAME]

If you ignored a library by mistake you can run the same command again and omit the id, or you can just delete the key entirely by running the following command

$ docker exec -ti watchstate console servers:edit --delete --key options.ignore -- [SERVER_NAME]

Q: I get tired of writing the whole command everytime is there an easy way run the commands?

Since there is no way to access the command interface outside docker, you can create small shell script to at least omit part of command that you have to write for example, to create shortcut for docker command do the following:

$ echo 'docker exec -ti watchstate console "$@"' > ws
$ chmod +x ws

after that you can do ./ws command for example, ./ws db:list

Sometimes there are problems related to HTTP/2 in the underlying library we use, so before reporting bug please try running the following command

$ docker exec -ti watchstate console servers:edit --key options.client.http_version --set 1.0 -- [SERVER_NAME]

if it does not fix your problem, please open issue about it.

Q: My sync operations are failing due to timeout can I increase that?

We use symfony/httpClient internally, So any options available in configuration section, can be used under options.client. key for example if you want to increase the timeout you can do

$ docker exec -ti watchstate console servers:edit --key options.client.timeout --set 600 -- [SERVER_NAME]

Q: Can I search my server remote libraries?

Yes, you can search your backend media servers. You can use --search '[searchTerm]' or --search-id [backend_media_id]. For example, to search for specific title keyword run the following command:

$ docker exec -ti console server servers:remote --search 'Gundam' -- [SERVER_NAME]

or if you want to get a specific item metadata run the following command:

$ docker exec -ti console server servers:remote --search-id 2514 -- [SERVER_NAME]

Optional flags that can be used with `--search` or `--search-id`

--search-raw Return unfiltered response.
--search-limit To limit returned results. Defaults to 25.
--search-output Set output style, it can be yaml or json. Defaults to json.

Q: Is it possible to look for possible unmatched items?

Yes, You can use the flag --search-mismatch '[library_id]' in servers:remote, For example

first get your library id by running the following command

$ docker exec -ti watchstate console servers:remote --list-libraries -- [SERVER_NAME]

it should display something like

ID	Title	Type	Ignored	Supported
2	Movies	movie	No	Yes
1	shows	show	No	Yes
17	Audio Books	artist	Yes	No

Then choose the library id that you want to scan, after that run the following command:

$ docker exec -ti console server servers:remote --search-mismatch [ID e.g. 2] --search-coef 60 -- [SERVER_NAME]

Optional flags that can be used with `--search-mismach`

--search-coef How much in percentage the title has to be in path to be marked as matched item. Defaults to 50.0.
--search-output Set output style, it can be yaml or json. Defaults to json.

Q: Which external ids supported for Plex?

tvdb://(id) New Plex Agent
imdb://(id) New Plex Agent
tmdb://(id) New Plex Agent
com.plexapp.agents.imdb://(id)?lang=en (Lagecy plex agent)
com.plexapp.agents.tmdb://(id)?lang=en (Lagecy plex agent)
com.plexapp.agents.themoviedb://(id)?lang=en (Lagecy plex agent)
com.plexapp.agents.thetvdb://(seriesId)?lang=en (Lagecy plex agent)
com.plexapp.agents.xbmcnfo://(id)?lang=en (XBMC NFO parser agent)
com.plexapp.agents.xbmcnfotv://(id)?lang=en (XBMC NFO parser agent for tv)
com.plexapp.agents.hama://(db)\d?-(id)?lang=en (hama agent is multi db source agent)

Q: Which external ids supported for Jellyfin/Emby?

imdb://(id)
tvdb://(id)
tmdb://(id)
tvmaze://(id)
tvrage://(id)
anidb://(id)

Q: What does mapper mean?

A Mapper is class that have list of all external ids that point to record in storage. think of it as dictionary that reference to specific item.

Memory Mapper (Default)

Memory mapper is the Default mapper, it uses memory to load the entire state table into memory, which in turn leads to better performance. you shouldn't use the other mapper unless you are running into memory problems.

Direct Mapper

Direct mapper is suitable for more memory constraint systems, it just loads the external ids mapping into memory, however it does not keep the state into memory, thus uses less memory compared to MemoryMapper, But the trade-off is it's slower than MemoryMapper.

Comparison between mappers

Operation	Memory Mapper	Direct Mapper
Memory Usage	(✗) Higher	(✓) Lower
Matching Speed	(✓) Faster	(✗) Slower
DB Operations	(✓) Faster	(✗) Slower

11 KiB Raw Blame History

FAQ