Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explain how to install subtitles in Docker #1136

Merged
merged 2 commits into from
Oct 22, 2024

Conversation

p0358
Copy link
Contributor

@p0358 p0358 commented Sep 28, 2024

Server-side fonts are used for subtitle burn-in, so it might be of interest to users to install custom fonts there.

Apparently it's enough to mount a custom font directory into for example /usr/local/share/fonts/custom (the custom part is arbitrary name, but the primary /usr/local/share/fonts folder shouldn't be mounted itself as it also has .uuid file there, so a subdir needs to be created.

And once that's done, the fontcache will apparently be automatically updated on container restart. So that just works out of the box with no changes to Jellyfin required at all.

Also did some changes to section where font types are explained.

How to install them depends on the operating system or container being used.

This is meant to both suggest people to look into Docker docs if they use Docker container, and to also not have some newbie install fonts on host OS while using a container and be confused why that doesn't work, this slight addition will hopefully prevent that.

Also added some things to Fallback Fonts section to hopefully make it clear how that feature works and in which direction the fonts go there.

@felix920506
Copy link
Member

There is already an existing pull request that is aiming to document this. #1129

@p0358
Copy link
Contributor Author

p0358 commented Sep 28, 2024

Oh, didn't see that one, what a coincidence then (given it was made at similar time). But... looking at it, I believe my approach is a bit better:

  • /usr/share/fonts is where existing system fonts installed by APT are at, if it gets mounted and replaced, I'm afraid it might end up actually breaking more things (where someone might not have all the default fonts, and they might be needed too...), while /usr/local/share/fonts is the designated place for manually putting custom fonts in
  • I see no reason for mounting /usr/share/fontconfig, at least it doesn't seem the reason was explained there at all (and as for the font cache itself, it is gonna get re-generated on container restart automatically already, so there seems to be no need if that's why this bind was added)

@p0358
Copy link
Contributor Author

p0358 commented Sep 28, 2024

Actually, I see why that was done, it seems to be because it was written to mount the exact same fonts from host... So I'm also not sure if that's really ideal then, personally I'd want some extra fonts for particular media to be installed just in the container instead of having to pollute the host system with these fonts for no particular reason. I think also most people would host Jellyfin on a Linux server rather than desktop to have these fonts already (or on Windows desktop where it wouldn't apply), plus most people probably download up custom fonts by default by just grabbing their files from somewhere instead of using APT. Plus I don't know if mounting /usr/share/fontconfig wouldn't have some risk of breaking things if the base host distro isn't Debian-based and its packages use some custom font paths in the files there...

@felix920506
Copy link
Member

We would prefer you leave feedback on that PR instead of having 2 competing ones. We generally don't want 2 PRs doing the same thing for documentation unless one of them is abandoned.

Copy link
Member

@felix920506 felix920506 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please include instructions on how to include fallback fonts in container situations as well.

docs/general/administration/configuration.md Outdated Show resolved Hide resolved

### Client Side System Fonts

The system fonts installed on the client devices are used to display the text in the client interface as well as render subtitles for some clients. How to install them depends on the operating system.

### Fallback Fonts

The `Fallback Fonts` option is currently used by the web client to render subtitles only. This can be set to a folder containing fonts for this purpose. These fonts are limited to a total size of 20MB. Lightweight formats optimized for web like woff2 are recommended. A tool to convert normal TrueType (`.ttf`) and OpenType (`.otf`) fonts to woff2 can be found [in their repo](https://github.com/google/woff2).
The `Fallback Fonts` option is currently used by the web client to render subtitles only. This can be set to a folder on the server containing fonts for this purpose, which will then be streamed to the client during playback, negating the need to manually install them to all clients locally. These fonts are limited to a total size of 20 MB. Lightweight formats optimized for web like woff2 are recommended. A tool to convert normal TrueType (`.ttf`) and OpenType (`.otf`) fonts to woff2 can be found [in their repo](https://github.com/google/woff2).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is inaccurate. The clients that use this will not use local fonts, and the clients that use local fonts will not use this

@jellyfin-bot
Copy link

Cloudflare Pages deployment

Latest commit 46fe1d25b676360bc40a585dc7afa316a42436a0
Status ✅ Deployed!
Preview URL https://1b5dbd72.jellyfin-org.pages.dev
Type 🔀 Preview

@p0358
Copy link
Contributor Author

p0358 commented Oct 22, 2024

Okay so I changed the description of fallback fonts to be re-worded and hopefully make it crystal-clear what the original intent of the feature is (before this change I was still somewhat misguided), in accordance with this comment: jellyfin/jellyfin#12511 (comment)

Please include instructions on how to include fallback fonts in container situations as well.

I added one more paragraph for it, but skipped it in the Compose section currently. It basically boils down to mounting a custom directory just like a media path in principle and then setting a dir in Jellyfin settings. But I wasn't really sure how to convey that. Current wording doesn't say explicitly that /media1 has to be then added as a library path in the UI, probably figuring it should be obvious enough to the people at that point.

It's only really server-side font that's special in the way that you have to mount it into correct designated location, but then don't have to configure anything else in Jellyfin afterwards.

Let me know if you have further suggestions, I feel like it might still not be perfect.

Copy link
Member

@solidsnake1298 solidsnake1298 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.

@felix920506 felix920506 merged commit 21e9387 into jellyfin:master Oct 22, 2024
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants