docs: Add more documentation for video transcoding settings.

[kevincox]

This adds documentation on many of the video transcoding settings ffmpeg.*. I focused the documentation on values that aren't just passthough to ffmpeg settings but that are custom to Immich.

[mmomjian]

I feel like this should be written up in the Immich docs, not as comments in a file.

[danieldietzler]

I agree, this shouldn't be a comment in the code as people who read the code typically know how to figure it out themselves anyways. If anything, this should help people figuring out the correct setting in the GUI

[mertalev]

It can go in the transcode policy description in a more condensed form. Also, the use of "optimal" as the resolution-based policy has always bothered me. Calling it "resolution" would be easier to understand.

[kevincox]

Can you clarify where you would like to see this?

[kevincox]

the use of "optimal" as the resolution-based policy has always bothered me. Calling it "resolution" would be easier to understand.

A nice improvement would be to separate out resolution and bitrate into flags rather than presets. Right now you can pick either but not both, example (I would like to transcode if either resolution or bitrate is over the preference). Or maybe it would be better to specify this similar to video formats where there is allowed and the target when transcoding specified separately. So you would have transcode policy Always, Required, Never then have targetBitrate, maxBitrate and targetResolution, maxResolution. But that is a bigger change than just documenting the current state.

[mertalev]

In the video transcoding settings in the admin UI.

[kevincox]

Hmm, the problem with putting it there is that if you are setting the values from the config file you can't actually see the descriptions of individual settings.

Screencast.from.2024-10-12.13-03-32.webm

It also doesn't list the settings "keyword". Maybe we need some sort of documentation that can appear both in the UI and in some place for people using the config file?

[mertalev]

I agree setting them as toggles would be nice to mix and match. It'd implicitly document how it works as well, such as having toggles for HDR etc.

Something like this, perhaps:

"videosToTranscode": {
    "hdr": true,
    "nonAcceptedCodec": true,
    "aboveTargetResolution": false,
    "aboveMaxBitrate": false
}

[mertalev]

Hmm, the problem with putting it there is that if you are setting the values from the config file you can't actually see the descriptions of individual settings.

Screencast.from.2024-10-12.13-03-32.webm

It also doesn't list the settings "keyword". Maybe we need some sort of documentation that can appear both in the UI and in some place for people using the config file?

Hmm, I guess putting in the docs and linking to it in the admin UI would be best. There'd be more room to explain config file usage that way. It's okay to put it in the section you mentioned in the OP for the scope of this PR, but in the future it'd be nicer to have a separate transcoding page instead.

[github-actions]

📖 Documentation deployed to pr-13388.preview.immich.app

[alextran1502]

Thank you for the PR. However, the subtitles in the settings are self-explanatory, and breaking them down in the documentation will cause a mismatch when we change them, creating a maintenance burden. I will close the PR for the reason above.

[kevincox]

The settings UI is one thing but there is currently zero documentation for the config file. I had to read the source to figure it out which I assume is not considered acceptable UX.

[alextran1502]

@kevincox ah that is fair, sorry I misunderstood the purpose of the PR

[mertalev]

A few minor nits, otherwise looks good!