asyncyt.encoding module

encoding.py

Rich encoding configuration models for AsyncYT.

class asyncyt.encoding.AudioEncodingConfig(*, codec: AudioCodec | None = None, bitrate: str | None = None, quality: Annotated[int | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=10)] = None, sample_rate: int | None = None, channels: AudioChannels | None = None, extra_args: List[str] = <factory>)[source]

Bases: BaseModel

Fine-grained audio encoding settings.

Parameters:

  • codec – FFmpeg audio codec (e.g. aac, libmp3lame, libopus).

  • bitrate – Target audio bitrate, e.g. "192k", "320k".

  • quality – VBR quality (codec-specific scale, e.g. 0-9 for libmp3lame).

  • sample_rate – Output sample rate in Hz, e.g. 44100, 48000.

  • channels – Number of output channels ("1" mono, "2" stereo …).

  • extra_args – Raw FFmpeg audio args appended verbatim.

class Config[source]

Bases: object

use_enum_values = True
bitrate: Annotated[str | None, Field(description="Audio bitrate e.g. '192k'")]
channels: Annotated[AudioChannels | None, Field(description='Output channel count')]
codec: Annotated[AudioCodec | None, Field(description='Audio codec')]
extra_args: Annotated[List[str], Field(default_factory=list, description='Raw FFmpeg audio args appended verbatim')]
model_config = {'use_enum_values': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

quality: Annotated[int | None, Field(ge=0, le=10, description='VBR quality (libmp3lame: 0=best…9=worst; libopus: ignored; aac: 0-5)')]
sample_rate: Annotated[int | None, Field(description='Output sample rate in Hz')]
to_ffmpeg_args() → List[str][source]

Produce a flat list of FFmpeg CLI args from this config.

class asyncyt.encoding.EncodingConfig(*, video: VideoEncodingConfig | None = None, audio: AudioEncodingConfig | None = None, overwrite: bool = False, extra_global_args: List[str] = <factory>)[source]

Bases: BaseModel

Combined video + audio encoding settings, plus container-level options.

Attach this to DownloadConfig.encoding to get full control over how yt-dlp invokes FFmpeg for remuxing/re-encoding.

Parameters:

  • video – Video encoding settings.

  • audio – Audio encoding settings.

  • overwrite – Pass -y to FFmpeg (overwrite existing files).

  • extra_global_args – Raw args added before input inside the --ppa value, e.g. ["-threads", "4"].

class Config[source]

Bases: object

use_enum_values = True
audio: Annotated[AudioEncodingConfig | None, Field(None, description='Audio encoding')]
build_extract_audio_ppa() → str | None[source]

Build a --postprocessor-args value for the ExtractAudio PP.

build_merger_ppa() → str | None[source]

Build a --postprocessor-args value for the Merger PP. Only injects extra global args (the merger just muxes, no re-encode).

build_video_convertor_ppa() → str | None[source]

Build a --postprocessor-args value for the VideoConvertor PP.

Returns None if there are no encoding args to inject.

extra_global_args: List[str]
model_config = {'use_enum_values': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

overwrite: Annotated[bool, Field(False, description='Overwrite existing output files (-y)')]
video: Annotated[VideoEncodingConfig | None, Field(None, description='Video encoding')]
class asyncyt.encoding.VideoEncodingConfig(*, codec: VideoCodec | None = None, crf: Annotated[int | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=63)] = None, bitrate: str | None = None, maxrate: str | None = None, bufsize: str | None = None, preset: Preset | None = None, tune: TuneOption | None = None, pixel_format: PixelFormat | None = None, width: Annotated[int | None, ~annotated_types.Gt(gt=0)] = None, height: Annotated[int | None, ~annotated_types.Gt(gt=0)] = None, fps: Annotated[int | float | None, ~annotated_types.Gt(gt=0)] = None, extra_args: List[str] = <factory>)[source]

Bases: BaseModel

Fine-grained video encoding settings.

All values are optional — only set ones are forwarded to FFmpeg via yt-dlp’s --postprocessor-args / --ppa mechanism.

Parameters:

  • codec – FFmpeg video codec (e.g. libx264, hevc_nvenc).

  • crf – Constant Rate Factor — quality vs. size (0 = lossless, 51 = worst). Not valid for hardware encoders; ignored automatically when bitrate is set (CRF and CBR are mutually exclusive).

  • bitrate – Target video bitrate, e.g. "2M", "800k".

  • maxrate – Maximum bitrate cap (used with bufsize for VBV).

  • bufsize – VBV buffer size, e.g. "4M".

  • preset – Encoding speed preset (ultrafast … placebo).

  • tune – x264/x265 tune option (film, animation, grain …).

  • pixel_format – Output pixel format (yuv420p, yuv420p10le …).

  • width – Output width in pixels (keeps aspect ratio when height omitted).

  • height – Output height in pixels (keeps aspect ratio when width omitted).

  • fps – Force output frame-rate, e.g. 30, 23.976.

  • extra_args – Raw FFmpeg video args appended verbatim, e.g. ["-profile:v", "high", "-level", "4.1"].

class Config[source]

Bases: object

use_enum_values = True
bitrate: Annotated[str | None, Field(description="Target video bitrate e.g. '2M'")]
bufsize: Annotated[str | None, Field(description="VBV buffer size e.g. '8M'")]
codec: Annotated[VideoCodec | None, Field(description='Video codec')]
crf: Annotated[int | None, Field(ge=0, le=63, description='Constant Rate Factor (0=lossless, typical 18-28 for x264)')]
extra_args: Annotated[List[str], Field(default_factory=list, description='Raw FFmpeg video args appended verbatim')]
fps: Annotated[int | float | None, Field(gt=0, description='Output frame rate')]
height: Annotated[int | None, Field(gt=0, description='Output height in pixels')]
maxrate: Annotated[str | None, Field(description="Max bitrate cap e.g. '4M'")]
model_config = {'use_enum_values': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pixel_format: Annotated[PixelFormat | None, Field(description='Output pixel format')]
preset: Annotated[Preset | None, Field(description='Encoding speed preset')]
to_ffmpeg_args() → List[str][source]

Produce a flat list of FFmpeg CLI args from this config.

tune: Annotated[TuneOption | None, Field(description='x264/x265 tune option')]
width: Annotated[int | None, Field(gt=0, description='Output width in pixels')]