baycone 0.7.0__tar.gz

baycone-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filip Klopec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

baycone-0.7.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: baycone
+Version: 0.7.0
+Summary: Transcode videos into streaming-friendly MP4 with ffmpeg, as a Python library or a command
+Keywords: ffmpeg,transcoding,video,mp4,h264,hevc,jellyfin,media-library
+Author: theobaldik
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Typing :: Typed
+Requires-Dist: charset-normalizer>=3.5.2
+Maintainer: theobaldik
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/theobaldik/baycone
+Project-URL: Source, https://github.com/theobaldik/baycone
+Project-URL: Documentation, https://github.com/theobaldik/baycone#readme
+Project-URL: Changelog, https://github.com/theobaldik/baycone/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/theobaldik/baycone/issues
+Project-URL: Docker image, https://hub.docker.com/r/theobaldik/baycone
+Description-Content-Type: text/markdown
+
+# Baycone
+
+**Transcode videos into streaming-friendly MP4 with ffmpeg — as a Python library or a command.**
+
+Baycone turns a video file into an MP4 that plays everywhere and starts instantly: h264 or hevc video, AAC audio and
+the moov atom up front. It only re-encodes what needs it, picks the audio tracks you want and never leaves a
+half-written file behind.
+
+This package is the pipeline behind the [Baycone Docker image](https://hub.docker.com/r/theobaldik/baycone), which
+watches media libraries and processes new files automatically.
+
+## Features
+
+- Two-pass `libx264` / `libx265` encode to a target bitrate, never above the source's
+- Copies streams that are already within limits; a container mismatch alone is fixed by a remux
+- Scales down to fit 1920×1080 (configurable), crops black bars and tone maps HDR10 / HLG to SDR
+- Keeps the original audio language plus your preferred ones, one track per language at the preferred channel count
+- Extracts text subtitles to UTF-8 `.srt` files
+- Detects copies that were cut off, kills a hung ffmpeg, and resumes an interrupted encode from its second pass
+- Writes the output in one step after it is safely on disk; the input file is never modified
+
+## Requirements
+
+- Python 3.14
+- `ffmpeg` and `ffprobe` on `PATH`, built with `libx264`, `libx265` and `libzimg` (most distribution builds are)
+
+## Installation
+
+```bash
+pip install baycone
+# or, for the command only
+uv tool install baycone
+```
+
+## Command line
+
+```bash
+baycone-cli movie.mkv                          # result in _baycone_processed/movie.mp4 next to the input
+baycone-cli movie.mkv --output /media/out.mp4
+baycone-cli movie.mkv -l cze -l eng -v 1800    # audio languages in order, video bitrate in kbps
+baycone-cli movie.mkv --codec hevc
+baycone-cli movie.mkv --remux-only             # never encode, only remux into MP4
+baycone-cli movie.mkv --info                   # print the analysis as JSON and exit
+```
+
+| Flag                    | Default                | Description                                             |
+|-------------------------|------------------------|---------------------------------------------------------|
+| `--output`              | `_baycone_processed/`  | Output file                                             |
+| `--work-dir`            | `.baycone/cli/`        | Temporary files; the default one is removed afterwards  |
+| `-l`, `--language`      | `original` `eng` `cze` | Audio language to keep, repeatable, in order            |
+| `-v`, `--video-bitrate` | `2250`                 | Target video bitrate in kbps                            |
+| `-a`, `--audio-bitrate` | `64`                   | Target audio bitrate per channel in kbps                |
+| `--codec`               | `h264`                 | Target video codec, `h264` or `hevc`                    |
+| `--subtitles`           | none                   | Subtitle language to extract to `.srt`, repeatable      |
+| `--remux-only`          | off                    | Copy every stream, only remux into the target container |
+| `--info`                | off                    | Print the analysis as JSON and exit                     |
+| `--ffmpeg`, `--ffprobe` | `ffmpeg`, `ffprobe`    | Binaries to use                                         |
+
+Exit codes: `0` success, `1` invalid arguments, `2` the file could not be processed.
+
+## Library
+
+```python
+from pathlib import Path
+
+from baycone import BayconeError, Encoder, EncodingSettings, Job
+
+settings = EncodingSettings(target_video_bitrate=1800, target_audio_languages=["original", "eng"])
+job = Job(input_file=Path("movie.mkv"), output_file=Path("out/movie.mp4"), work_dir=Path("work"))
+
+try:
+    Encoder(settings, on_progress=lambda step, percent: print(step, percent)).process(job)
+except BayconeError as e:
+    ...  # the input is untouched and no output is left behind
+```
+
+- `EncodingSettings` holds every encoding setting: allowed codecs and containers, targets and limits.
+- `Encoder.process()` returns the output path or raises a `BayconeError`: `InsufficientSpaceError` before anything is
+  written, `InvalidFileError` for an unreadable or truncated file, `EncodingError` when ffmpeg fails, and
+  `SourceChangedError` when the input changed while it was processed.
+- Keep `work_dir` on the same filesystem as `output_file`, otherwise publishing has to copy the file.
+- `Analyzer(settings).analyze(path)` returns the analysis alone, without encoding anything.
+- The library logs through `logging` under `baycone.*` and configures no handlers. It is fully typed.
+
+## Links
+
+- [Source code and documentation](https://github.com/theobaldik/baycone)
+- [Changelog](https://github.com/theobaldik/baycone/blob/master/CHANGELOG.md)
+- [Issues](https://github.com/theobaldik/baycone/issues)
+- [Docker image](https://hub.docker.com/r/theobaldik/baycone)
+
+Released under the [MIT License](https://github.com/theobaldik/baycone/blob/master/LICENSE).

baycone-0.7.0/baycone/__init__.py

@@ -0,0 +1,19 @@
+from baycone.encoding import Analyzer, Encoder, FileInfo, Job, ProgressCallback, VideoStream
+from baycone.errors import BayconeError, EncodingError, InsufficientSpaceError, InvalidFileError, SourceChangedError
+from baycone.settings import EncodingSettings, FFmpegTools
+
+__all__ = [
+    "Analyzer",
+    "BayconeError",
+    "Encoder",
+    "EncodingError",
+    "EncodingSettings",
+    "FFmpegTools",
+    "FileInfo",
+    "InsufficientSpaceError",
+    "InvalidFileError",
+    "Job",
+    "ProgressCallback",
+    "SourceChangedError",
+    "VideoStream",
+]

baycone-0.7.0/baycone/audio.py

@@ -0,0 +1,128 @@
+from dataclasses import dataclass
+
+from baycone.settings import EncodingSettings
+from baycone.languages import BIBLIOGRAPHIC_TO_TERMINOLOGY
+
+UNDEFINED_LANGUAGE = "und"
+# Stands for the original track's language in `target_audio_languages`
+ORIGINAL_LANGUAGE = "original"
+
+TRACK_NAMES: dict[int, str] = {
+    1: "Mono",
+    2: "Stereo",
+    3: "Stereo 2.1",
+    6: "Surround 5.1",
+    8: "Surround 7.1",
+    9: "Surround 7.2",
+}
+
+# Tracks with any of these ffprobe dispositions are never kept; 'dub' is not one of them, dubs are regular languages
+SPECIAL_DISPOSITIONS: tuple[str, ...] = (
+    "comment",
+    "visual_impaired",
+    "descriptions",
+    "hearing_impaired",
+    "clean_effects",
+    "karaoke",
+    "lyrics",
+)
+
+
+# aac bitrate needed for the same quality, per kbps of the source codec
+AAC_EFFICIENCY: dict[str, float] = {"opus": 1.5, "vorbis": 1.1, "mp3": 0.75, "ac3": 0.65, "dts": 0.5}
+
+
+def normalize_language(code: str) -> str:
+    code = code.strip().lower()
+    # ISO 639-2/B and /T codes both occur in the wild, MP4 requires /T
+    return BIBLIOGRAPHIC_TO_TERMINOLOGY.get(code, code) or UNDEFINED_LANGUAGE
+
+
+def cap_bitrate(source: int, target: int) -> int:
+    """Never upscales, falls back to `target` when the source bitrate is unknown."""
+    return min(source, target) if source > 0 else target
+
+
+@dataclass
+class AudioStream:
+    index: int = 0
+    shall_encode: bool = False
+    codec: str = ""
+    channel_bitrate: int = 0
+    channels: int = 0
+    lang: str = UNDEFINED_LANGUAGE
+    title: str = ""
+    original: bool = False
+    special: bool = False
+
+    @property
+    def overall_bitrate(self) -> int:
+        return self.channel_bitrate * self.channels
+
+    @property
+    def aac_channel_bitrate(self) -> int:
+        return int(self.channel_bitrate * AAC_EFFICIENCY.get(self.codec, 1.0))
+
+    @property
+    def aac_overall_bitrate(self) -> int:
+        return self.aac_channel_bitrate * self.channels
+
+    def generate_track_name(self) -> str:
+        return TRACK_NAMES.get(self.channels, "")
+
+
+@dataclass
+class AudioTrack:
+    stream: AudioStream
+    bitrate: int = 0  # kbps, 0 copies the stream
+    default: bool = False
+
+    @property
+    def title(self) -> str:
+        return self.stream.generate_track_name()
+
+    @property
+    def disposition(self) -> str:
+        flags = [name for name, enabled in (("default", self.default), ("original", self.stream.original)) if enabled]
+        return "+".join(flags) or "0"
+
+
+def _pick_by_channels(versions: list[AudioStream], preferred: int) -> AudioStream:
+    """The fewest channels at or above `preferred`, else the most below it; ties keep the source order."""
+    at_least = [s for s in versions if s.channels >= preferred]
+    if at_least:
+        return min(at_least, key=lambda s: s.channels)
+    return max(versions, key=lambda s: s.channels)
+
+
+def select_audio_tracks(streams: list[AudioStream], settings: EncodingSettings) -> list[AudioTrack]:
+    """The configured languages in order, one track per language; the original alone when none of them is found."""
+    candidates = [s for s in streams if not s.special]
+
+    if candidates:
+        original = next((s for s in candidates if s.original), candidates[0])
+        languages = [
+            original.lang if lang.strip().lower() == ORIGINAL_LANGUAGE else normalize_language(lang)
+            for lang in settings.target_audio_languages
+        ]
+        selected = []
+        for language in dict.fromkeys(languages):
+            versions = [s for s in candidates if s.lang == language]
+            if versions:
+                selected.append(_pick_by_channels(versions, settings.target_audio_channels))
+        selected = selected or [original]
+    else:
+        selected = streams[:1]
+
+    return [
+        AudioTrack(
+            stream=stream,
+            bitrate=(
+                cap_bitrate(stream.aac_overall_bitrate, settings.target_audio_channel_bitrate * stream.channels)
+                if stream.shall_encode
+                else 0
+            ),
+            default=i == 0,
+        )
+        for i, stream in enumerate(selected)
+    ]