forge-mvc-audio 1.0.0b16__tar.gz

forge_mvc_audio-1.0.0b16/LICENSE

@@ -0,0 +1,36 @@
+Forge — Licence propriétaire / source disponible
+
+Copyright (c) Roger Lequette.
+Tous droits réservés.
+
+Le code source de Forge est mis à disposition uniquement pour lecture, étude,
+évaluation et usage éducatif personnel.
+
+Sauf autorisation écrite préalable de Roger Lequette, il est interdit de :
+
+- utiliser Forge dans un cadre professionnel, commercial ou institutionnel ;
+- utiliser Forge pour une prestation client ;
+- intégrer Forge dans un produit, service, SaaS, application vendue ou solution
+  déployée pour un tiers ;
+- redistribuer Forge, modifié ou non ;
+- publier une version modifiée de Forge ;
+- vendre, louer, sous-licencier ou exploiter commercialement Forge ;
+- supprimer ou modifier les mentions de copyright et de licence.
+
+Les usages autorisés sans autorisation écrite préalable sont limités à :
+
+- lire le code ;
+- étudier son fonctionnement ;
+- tester Forge à titre personnel ;
+- l'utiliser dans un cadre éducatif personnel ou pédagogique non commercial ;
+- évaluer le framework avant une éventuelle demande d'autorisation.
+
+Toute utilisation non explicitement autorisée par cette licence nécessite une
+autorisation écrite préalable de Roger Lequette.
+
+Cette licence pourra évoluer ultérieurement. Toute version publiée de Forge
+reste soumise à la licence présente dans son dépôt au moment de sa récupération.
+
+LE LOGICIEL EST FOURNI « TEL QUEL », SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU
+IMPLICITE. EN AUCUN CAS LE DÉTENTEUR DU COPYRIGHT NE POURRA ÊTRE TENU
+RESPONSABLE DE TOUT DOMMAGE DÉCOULANT DE L'UTILISATION DE CE LOGICIEL.

forge_mvc_audio-1.0.0b16/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: forge-mvc-audio
+Version: 1.0.0b16
+Summary: Forge Audio — module opt-in pour l'upload, le sondage de métadonnées (ffprobe), le transcodage MP3 (ffmpeg) et la lecture audio en streaming (HTTP Range). Sans état : aucune base de données. Worker CLI forge audio:doctor.
+Author: Roger Lequette
+License-Expression: LicenseRef-Forge-Proprietary
+Project-URL: Homepage, https://github.com/caucrogeGit/Forge
+Project-URL: Repository, https://github.com/caucrogeGit/Forge
+Project-URL: Documentation, https://forgemvc.com/docs/forge/audio/
+Keywords: python,mvc,forge,audio,ffmpeg,mp3,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: forge-mvc<2,>=1.0.0b16
+Dynamic: license-file
+
+# forge-mvc-audio
+
+Module **opt-in** Forge pour la gestion audio : upload, sondage de métadonnées,
+transcodage MP3 et lecture en streaming. **Sans état** (aucune base de données).
+
+## Statut : Beta — opt-in officiel
+
+`forge-mvc-audio` fournit une chaîne audio complète et **sobre**, calquée sur
+`forge-mvc-video` mais **sans la machinerie à état** (pas de table SQL, pas de
+suivi de jobs, pas de file de transcodage). C'est un choix délibéré : les
+opérations audio sont synchrones et la lecture retrouve les fichiers par `uuid`
+sur le disque.
+
+> **ffmpeg / ffprobe** sont des binaires **système** (pas des dépendances pip).
+> Le module se branche sans eux (le service de lecture fonctionne), mais le
+> sondage exige `ffprobe` et le transcodage exige `ffmpeg`.
+> `forge audio:doctor` signale leur absence.
+
+Installation (mode éditable depuis les sources) :
+
+```bash
+pip install -e packages/forge-mvc-audio/
+```
+
+## Ce que contient le module
+
+- `config` — `AudioConfig` + `load_audio_config()` (configuration depuis
+  `FORGE_AUDIO_*`, valeurs par défaut sûres).
+- `storage` — disposition **uuid-based** des fichiers (le nom utilisateur
+  n'apparaît jamais dans le chemin → anti-traversal par construction).
+- `probe` — `probe_audio()` via `ffprobe` : durée, codec, bitrate, sample rate,
+  nombre de canaux, conteneur. Sert aussi de validation profonde (rejet d'un
+  fichier sans flux audio).
+- `ingest` — `ingest_audio(data, filename)` : valide (taille, extension), stocke
+  la source, retourne un enregistrement (`uuid`, chemin, taille, MIME).
+- `transcode` — `transcode_to_mp3()` via `ffmpeg` (profil MP3 192 kbps, stéréo,
+  métadonnées d'origine retirées). Constructeurs de commande **purs**, runner
+  injectable (testable sans ffmpeg).
+- `http` — `register_audio_routes(router)` : route `GET /audio/{uuid}` servie en
+  **streaming HTTP Range** (seek), Bearer token optionnel
+  (`FORGE_AUDIO_API_TOKEN`).
+- `cli.doctor` — `forge audio:doctor` : diagnostic statique (package, config,
+  ffprobe, ffmpeg, routes).
+
+## Formats acceptés à l'upload
+
+`mp3`, `wav`, `ogg`, `flac`, `m4a`, `aac`. La sortie de transcodage est MP3.
+
+## Sécurité
+
+- Invocation `ffmpeg`/`ffprobe` en **liste d'arguments** (jamais `shell=True`).
+- Chemins **uuid-based** : le `uuid` de l'URL n'est qu'une clé de lookup, validée
+  comme un UUID — aucun *path traversal*.
+- Token Bearer optionnel sur la route de lecture (mode local ouvert par défaut).
+- L'auth vit dans ce module, **jamais** dans Forge Core.
+
+## Configuration (`FORGE_AUDIO_*`)
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `FORGE_AUDIO_FFMPEG_BIN` | `ffmpeg` | binaire ffmpeg |
+| `FORGE_AUDIO_FFPROBE_BIN` | `ffprobe` | binaire ffprobe |
+| `FORGE_AUDIO_STORAGE_ROOT` | `storage/audio` | racine de stockage |
+| `FORGE_AUDIO_MAX_UPLOAD_MB` | `200` | taille max d'upload |
+| `FORGE_AUDIO_MAX_DURATION_SECONDS` | `7200` | durée max (2 h) |
+| `FORGE_AUDIO_API_TOKEN` | *(absent)* | Bearer token de lecture (optionnel) |

forge_mvc_audio-1.0.0b16/README.md

@@ -0,0 +1,66 @@
+# forge-mvc-audio
+
+Module **opt-in** Forge pour la gestion audio : upload, sondage de métadonnées,
+transcodage MP3 et lecture en streaming. **Sans état** (aucune base de données).
+
+## Statut : Beta — opt-in officiel
+
+`forge-mvc-audio` fournit une chaîne audio complète et **sobre**, calquée sur
+`forge-mvc-video` mais **sans la machinerie à état** (pas de table SQL, pas de
+suivi de jobs, pas de file de transcodage). C'est un choix délibéré : les
+opérations audio sont synchrones et la lecture retrouve les fichiers par `uuid`
+sur le disque.
+
+> **ffmpeg / ffprobe** sont des binaires **système** (pas des dépendances pip).
+> Le module se branche sans eux (le service de lecture fonctionne), mais le
+> sondage exige `ffprobe` et le transcodage exige `ffmpeg`.
+> `forge audio:doctor` signale leur absence.
+
+Installation (mode éditable depuis les sources) :
+
+```bash
+pip install -e packages/forge-mvc-audio/
+```
+
+## Ce que contient le module
+
+- `config` — `AudioConfig` + `load_audio_config()` (configuration depuis
+  `FORGE_AUDIO_*`, valeurs par défaut sûres).
+- `storage` — disposition **uuid-based** des fichiers (le nom utilisateur
+  n'apparaît jamais dans le chemin → anti-traversal par construction).
+- `probe` — `probe_audio()` via `ffprobe` : durée, codec, bitrate, sample rate,
+  nombre de canaux, conteneur. Sert aussi de validation profonde (rejet d'un
+  fichier sans flux audio).
+- `ingest` — `ingest_audio(data, filename)` : valide (taille, extension), stocke
+  la source, retourne un enregistrement (`uuid`, chemin, taille, MIME).
+- `transcode` — `transcode_to_mp3()` via `ffmpeg` (profil MP3 192 kbps, stéréo,
+  métadonnées d'origine retirées). Constructeurs de commande **purs**, runner
+  injectable (testable sans ffmpeg).
+- `http` — `register_audio_routes(router)` : route `GET /audio/{uuid}` servie en
+  **streaming HTTP Range** (seek), Bearer token optionnel
+  (`FORGE_AUDIO_API_TOKEN`).
+- `cli.doctor` — `forge audio:doctor` : diagnostic statique (package, config,
+  ffprobe, ffmpeg, routes).
+
+## Formats acceptés à l'upload
+
+`mp3`, `wav`, `ogg`, `flac`, `m4a`, `aac`. La sortie de transcodage est MP3.
+
+## Sécurité
+
+- Invocation `ffmpeg`/`ffprobe` en **liste d'arguments** (jamais `shell=True`).
+- Chemins **uuid-based** : le `uuid` de l'URL n'est qu'une clé de lookup, validée
+  comme un UUID — aucun *path traversal*.
+- Token Bearer optionnel sur la route de lecture (mode local ouvert par défaut).
+- L'auth vit dans ce module, **jamais** dans Forge Core.
+
+## Configuration (`FORGE_AUDIO_*`)
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `FORGE_AUDIO_FFMPEG_BIN` | `ffmpeg` | binaire ffmpeg |
+| `FORGE_AUDIO_FFPROBE_BIN` | `ffprobe` | binaire ffprobe |
+| `FORGE_AUDIO_STORAGE_ROOT` | `storage/audio` | racine de stockage |
+| `FORGE_AUDIO_MAX_UPLOAD_MB` | `200` | taille max d'upload |
+| `FORGE_AUDIO_MAX_DURATION_SECONDS` | `7200` | durée max (2 h) |
+| `FORGE_AUDIO_API_TOKEN` | *(absent)* | Bearer token de lecture (optionnel) |

forge_mvc_audio-1.0.0b16/forge_mvc_audio/__init__.py

@@ -0,0 +1,43 @@
+"""Forge MVC Audio — module opt-in pour la gestion audio.
+
+Chaîne audio **complète et sans état** (aucune base de données) :
+
+- ``config`` — contrat de configuration (`AudioConfig`, `load_audio_config`) ;
+- ``storage`` — disposition uuid-based des fichiers (anti-traversal) ;
+- ``probe`` — métadonnées via ``ffprobe`` (durée, codec, bitrate, canaux…) ;
+- ``ingest`` — upload validé + stockage (``ingest_audio``) ;
+- ``transcode`` — conversion MP3 via ``ffmpeg`` (``transcode_to_mp3``) ;
+- ``http`` — lecture en streaming HTTP Range (``register_audio_routes``) ;
+- ``cli.doctor`` — diagnostic ``forge audio:doctor``.
+
+Volontairement **sobre** : pas de table SQL, pas de suivi de jobs, pas de file
+de transcodage. Les opérations sont synchrones et le service de lecture
+retrouve les fichiers par ``uuid`` sur le disque. ``ffmpeg``/``ffprobe`` sont
+des binaires système (pas des dépendances pip).
+
+Le module reste **opt-in** : l'application appelle ``register_audio_routes``
+explicitement. Aucune écriture dans le code utilisateur (charte §9).
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0b16"
+
+from forge_mvc_audio.config import AudioConfig, load_audio_config
+from forge_mvc_audio.http import register_audio_routes
+from forge_mvc_audio.ingest import AudioIngestError, ingest_audio
+from forge_mvc_audio.probe import AudioMetadata, AudioProbeError, probe_audio
+from forge_mvc_audio.transcode import FfmpegError, transcode_to_mp3
+
+__all__ = [
+    "AudioConfig",
+    "AudioIngestError",
+    "AudioMetadata",
+    "AudioProbeError",
+    "FfmpegError",
+    "ingest_audio",
+    "load_audio_config",
+    "probe_audio",
+    "register_audio_routes",
+    "transcode_to_mp3",
+]

forge_mvc_audio-1.0.0b16/forge_mvc_audio/cli/__init__.py

@@ -0,0 +1 @@
+"""Interface CLI du module opt-in Forge Audio (``forge audio:*``)."""

forge_mvc_audio-1.0.0b16/forge_mvc_audio/cli/doctor.py

@@ -0,0 +1,139 @@
+"""Diagnostic ``forge audio:doctor``.
+
+Diagnostic **statique** : ne lance aucun ``ffmpeg``, n'ouvre aucun fichier
+audio, ne touche à aucune base (il n'y en a pas). Il vérifie que l'environnement
+est prêt :
+
+1. le package ``forge_mvc_audio`` est importable et expose ``__version__`` ;
+2. ``load_audio_config()`` charge une configuration cohérente ;
+3. le binaire ``ffprobe`` est présent dans le PATH (validation/métadonnées) ;
+4. le binaire ``ffmpeg`` est présent dans le PATH (transcodage MP3) ;
+5. ``register_audio_routes`` est exposée (branchement HTTP).
+
+``ffmpeg``/``ffprobe`` absents → ``fail`` : sondage et transcodage les exigent.
+Convention alignée sur ``forge video:doctor`` / ``forge iot:doctor`` : statuts
+minuscules ``ok``/``warn``/``fail``/``skip``, dataclass ``CheckResult``.
+"""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from typing import Literal
+
+__all__ = [
+    "CheckResult",
+    "check_package_importable",
+    "check_config_loadable",
+    "check_ffprobe_present",
+    "check_ffmpeg_present",
+    "check_routes_registrable",
+    "run_all",
+    "print_report",
+    "has_failures",
+    "main",
+]
+
+Status = Literal["ok", "warn", "fail", "skip"]
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    status: Status
+    name: str
+    detail: str = ""
+
+
+def check_package_importable() -> CheckResult:
+    try:
+        import forge_mvc_audio
+
+        version = getattr(forge_mvc_audio, "__version__", None)
+    except Exception as exc:  # pragma: no cover — défensif
+        return CheckResult("fail", "package", f"import impossible : {exc}")
+    if not version:
+        return CheckResult("warn", "package", "importable mais sans __version__")
+    return CheckResult("ok", "package", f"forge_mvc_audio {version}")
+
+
+def check_config_loadable() -> CheckResult:
+    try:
+        from forge_mvc_audio.config import load_audio_config
+
+        cfg = load_audio_config()
+    except Exception as exc:  # pragma: no cover — défensif
+        return CheckResult("fail", "config", f"chargement impossible : {exc}")
+    return CheckResult(
+        "ok",
+        "config",
+        f"storage={cfg.storage_root}, max_upload={cfg.max_upload_mb} Mo, "
+        f"max_durée={cfg.max_duration_seconds}s",
+    )
+
+
+def _check_binary(name: str, bin_value: str, purpose: str) -> CheckResult:
+    path = shutil.which(bin_value)
+    if path is None:
+        return CheckResult(
+            "fail",
+            name,
+            f"`{bin_value}` introuvable dans le PATH — requis pour {purpose}",
+        )
+    return CheckResult("ok", name, path)
+
+
+def check_ffprobe_present() -> CheckResult:
+    from forge_mvc_audio.config import load_audio_config
+
+    return _check_binary(
+        "ffprobe", load_audio_config().ffprobe_bin, "la validation et les métadonnées"
+    )
+
+
+def check_ffmpeg_present() -> CheckResult:
+    from forge_mvc_audio.config import load_audio_config
+
+    return _check_binary(
+        "ffmpeg", load_audio_config().ffmpeg_bin, "le transcodage MP3"
+    )
+
+
+def check_routes_registrable() -> CheckResult:
+    try:
+        from forge_mvc_audio import register_audio_routes
+    except Exception as exc:  # pragma: no cover — défensif
+        return CheckResult("fail", "routes", f"register_audio_routes absente : {exc}")
+    if not callable(register_audio_routes):
+        return CheckResult("fail", "routes", "register_audio_routes non appelable")
+    return CheckResult("ok", "routes", "register_audio_routes exposée")
+
+
+def run_all() -> list[CheckResult]:
+    return [
+        check_package_importable(),
+        check_config_loadable(),
+        check_ffprobe_present(),
+        check_ffmpeg_present(),
+        check_routes_registrable(),
+    ]
+
+
+_TAGS = {"ok": "[OK]  ", "warn": "[WARN]", "fail": "[FAIL]", "skip": "[SKIP]"}
+
+
+def print_report(results: list[CheckResult]) -> None:
+    for r in results:
+        tag = _TAGS.get(r.status, "[????]")
+        line = f"{tag} {r.name}"
+        if r.detail:
+            line += f" — {r.detail}"
+        print(line)
+
+
+def has_failures(results: list[CheckResult]) -> bool:
+    return any(r.status == "fail" for r in results)
+
+
+def main(args: list[str] | None = None) -> int:
+    results = run_all()
+    print_report(results)
+    return 1 if has_failures(results) else 0

forge_mvc_audio-1.0.0b16/forge_mvc_audio/config.py

@@ -0,0 +1,83 @@
+"""Configuration Forge Audio.
+
+Charge la configuration du module audio depuis un mapping (``os.environ`` par
+défaut, ou un dict injecté pour les tests).
+
+Module **pur** : il ne lit aucun fichier, ne lance aucun ``ffmpeg`` et n'écrit
+nulle part. Il fixe uniquement le contrat de configuration.
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+__all__ = [
+    "DEFAULT_FFMPEG_BIN",
+    "DEFAULT_FFPROBE_BIN",
+    "DEFAULT_STORAGE_ROOT",
+    "DEFAULT_MAX_UPLOAD_MB",
+    "DEFAULT_MAX_DURATION_SECONDS",
+    "ENV_FFMPEG_BIN",
+    "ENV_FFPROBE_BIN",
+    "ENV_STORAGE_ROOT",
+    "ENV_MAX_UPLOAD_MB",
+    "ENV_MAX_DURATION_SECONDS",
+    "ENV_API_TOKEN",
+    "AudioConfig",
+    "load_audio_config",
+]
+
+DEFAULT_FFMPEG_BIN = "ffmpeg"
+DEFAULT_FFPROBE_BIN = "ffprobe"
+DEFAULT_STORAGE_ROOT = "storage/audio"
+DEFAULT_MAX_UPLOAD_MB = 200
+DEFAULT_MAX_DURATION_SECONDS = 7200
+
+ENV_FFMPEG_BIN = "FORGE_AUDIO_FFMPEG_BIN"
+ENV_FFPROBE_BIN = "FORGE_AUDIO_FFPROBE_BIN"
+ENV_STORAGE_ROOT = "FORGE_AUDIO_STORAGE_ROOT"
+ENV_MAX_UPLOAD_MB = "FORGE_AUDIO_MAX_UPLOAD_MB"
+ENV_MAX_DURATION_SECONDS = "FORGE_AUDIO_MAX_DURATION_SECONDS"
+ENV_API_TOKEN = "FORGE_AUDIO_API_TOKEN"
+
+
+@dataclass(frozen=True)
+class AudioConfig:
+    """Contrat de configuration du module audio."""
+
+    ffmpeg_bin: str = DEFAULT_FFMPEG_BIN
+    ffprobe_bin: str = DEFAULT_FFPROBE_BIN
+    storage_root: str = DEFAULT_STORAGE_ROOT
+    max_upload_mb: int = DEFAULT_MAX_UPLOAD_MB
+    max_duration_seconds: int = DEFAULT_MAX_DURATION_SECONDS
+    # Protection optionnelle des routes de lecture : si défini, un en-tête
+    # ``Authorization: Bearer <token>`` est exigé ; sinon les routes sont
+    # ouvertes (mode local/pédagogique). None = pas de token.
+    api_token: str | None = None
+
+
+def _int(source: Mapping[str, str], key: str, default: int) -> int:
+    raw = source.get(key)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        value = int(str(raw).strip())
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+def load_audio_config(source: Mapping[str, str] | None = None) -> AudioConfig:
+    """Construit un ``AudioConfig`` depuis ``source`` (``os.environ`` par défaut)."""
+    env = source if source is not None else os.environ
+    return AudioConfig(
+        ffmpeg_bin=(env.get(ENV_FFMPEG_BIN) or DEFAULT_FFMPEG_BIN).strip(),
+        ffprobe_bin=(env.get(ENV_FFPROBE_BIN) or DEFAULT_FFPROBE_BIN).strip(),
+        storage_root=(env.get(ENV_STORAGE_ROOT) or DEFAULT_STORAGE_ROOT).strip(),
+        max_upload_mb=_int(env, ENV_MAX_UPLOAD_MB, DEFAULT_MAX_UPLOAD_MB),
+        max_duration_seconds=_int(
+            env, ENV_MAX_DURATION_SECONDS, DEFAULT_MAX_DURATION_SECONDS
+        ),
+        api_token=env.get(ENV_API_TOKEN) or None,
+    )

forge_mvc_audio-1.0.0b16/forge_mvc_audio/http.py

@@ -0,0 +1,108 @@
+"""Lecture HTTP des fichiers audio — streaming Range, sans état.
+
+Branche une route de **lecture en streaming** sur un ``Router`` Forge :
+
+- ``GET /audio/{uuid}`` — sert le fichier audio en streaming avec support HTTP
+  **Range** (seek), via la primitive core ``Response.file``.
+
+Le chemin servi est **retrouvé sur le disque** à partir de l'``uuid`` (préférence
+au MP3 transcodé, sinon la source) — jamais depuis l'URL, et l'``uuid`` est
+validé comme UUID canonique → aucun *path traversal* possible.
+
+Sécurité (optionnelle, mirror Video/IoT) : si ``FORGE_AUDIO_API_TOKEN`` est
+défini, la route exige ``Authorization: Bearer <token>`` ; sinon elle est
+ouverte (mode local/pédagogique). L'auth vit dans ce module, **jamais** dans
+Forge Core.
+
+Le module reste **opt-in** : l'application appelle ``register_audio_routes``
+explicitement. Aucune écriture dans ``mvc/routes.py`` (charte §9).
+"""
+from __future__ import annotations
+
+import logging
+import secrets
+from pathlib import Path
+from typing import Any
+
+from core.http.response import Response
+
+from forge_mvc_audio.config import AudioConfig, load_audio_config
+from forge_mvc_audio.storage import resolve_playable_relpath
+
+__all__ = ["AudioHttpController", "register_audio_routes", "ROUTE_PLAYBACK"]
+
+logger = logging.getLogger(__name__)
+
+ROUTE_PLAYBACK = "/audio/{uuid}"
+
+_BEARER_PREFIX = "Bearer "
+
+
+def _extract_bearer_token(request: Any) -> str | None:
+    header = request.header("Authorization", None)
+    if not header or not header.startswith(_BEARER_PREFIX):
+        return None
+    return header[len(_BEARER_PREFIX):]
+
+
+def _is_authorized(request: Any, api_token: str | None) -> bool:
+    """Ouvert si ``api_token is None`` ; sinon Bearer == token (temps constant)."""
+    if api_token is None:
+        return True
+    provided = _extract_bearer_token(request)
+    if provided is None:
+        return False
+    return secrets.compare_digest(provided, api_token)
+
+
+def _error(code: str, status: int) -> Response:
+    return Response.json({"error": code}, status=status)
+
+
+class AudioHttpController:
+    """Handler HTTP de lecture audio, sans état (lookup disque par uuid)."""
+
+    def __init__(self, config: AudioConfig, *, api_token: str | None = None) -> None:
+        self._config = config
+        self._api_token = api_token
+
+    def stream(self, request: Any) -> Response:
+        if not _is_authorized(request, self._api_token):
+            return _error("unauthorized", 401)
+
+        uuid = request.route("uuid")
+        # Chemin retrouvé sur le disque (jamais depuis l'URL) ; uuid validé en
+        # interne par resolve_playable_relpath → pas de path traversal.
+        rel = resolve_playable_relpath(uuid, storage_root=self._config.storage_root)
+        if not rel:
+            return _error("not_found", 404)
+
+        path = Path(self._config.storage_root) / rel
+        if not path.is_file():
+            logger.warning("Forge Audio — fichier absent pour %s : %s", uuid, path)
+            return _error("file_missing", 404)
+
+        # Streaming + Range délégués à la primitive core.
+        return Response.file(path, request)
+
+
+def register_audio_routes(
+    router: Any,
+    *,
+    config: AudioConfig | None = None,
+) -> Any:
+    """Enregistre la route de lecture audio sur un ``Router`` Forge.
+
+    Appelée **explicitement** par l'application. Si ``config.api_token`` est
+    défini, la route exige un Bearer token. Retourne le ``router`` (chaînable).
+    """
+    if config is None:
+        config = load_audio_config()
+    controller = AudioHttpController(config, api_token=config.api_token)
+
+    router.add(
+        "GET", ROUTE_PLAYBACK, controller.stream,
+        name="audio_stream",
+        public=True, csrf=False, api=False,
+    )
+    return router

forge_mvc_audio-1.0.0b16/forge_mvc_audio/ingest.py

@@ -0,0 +1,73 @@
+"""Ingestion d'un fichier audio — sans état (aucune base de données).
+
+``ingest_audio`` valide (taille, extension), stocke la source à un emplacement
+**uuid-based**, et retourne un enregistrement. Fonction Python appelable depuis
+un contrôleur ou un script.
+
+Validation **basique** ici (taille + extension) ; la validation profonde par
+``ffprobe`` (vrai flux audio, durée ≤ max) appartient à ``probe_audio``. Aucun
+``ffmpeg`` n'est lancé : pas de traitement en ligne.
+"""
+from __future__ import annotations
+
+import mimetypes
+from uuid import uuid4
+
+from forge_mvc_audio.config import AudioConfig, load_audio_config
+from forge_mvc_audio.storage import (
+    ALLOWED_EXTENSIONS,
+    safe_extension,
+    store_original,
+)
+
+__all__ = ["AudioIngestError", "ingest_audio"]
+
+
+class AudioIngestError(ValueError):
+    """Upload refusé (taille, extension, fichier vide)."""
+
+
+def ingest_audio(
+    data: bytes,
+    filename: str,
+    *,
+    title: str | None = None,
+    config: AudioConfig | None = None,
+    uuid: str | None = None,
+) -> dict:
+    """Valide et stocke un fichier audio source.
+
+    Retourne un dict ``{uuid, title, original_path, size_bytes, mime_type}``.
+    Lève ``AudioIngestError`` si l'upload est refusé.
+    """
+    cfg = config or load_audio_config()
+
+    size = len(data)
+    if size == 0:
+        raise AudioIngestError("fichier vide")
+    max_bytes = cfg.max_upload_mb * 1024 * 1024
+    if size > max_bytes:
+        raise AudioIngestError(
+            f"audio trop volumineux : {size} octets > {max_bytes} "
+            f"(FORGE_AUDIO_MAX_UPLOAD_MB={cfg.max_upload_mb})"
+        )
+
+    ext = safe_extension(filename)
+    if ext not in ALLOWED_EXTENSIONS:
+        raise AudioIngestError(
+            f"extension non autorisée : {ext!r} "
+            f"(acceptées : {', '.join(sorted(ALLOWED_EXTENSIONS))})"
+        )
+
+    audio_uuid = uuid or str(uuid4())
+    original_path = store_original(data, audio_uuid, ext, storage_root=cfg.storage_root)
+    mime_type = mimetypes.guess_type(filename)[0]
+
+    clean_title = title.strip() if title and title.strip() else None
+    return {
+        "uuid": audio_uuid,
+        "title": clean_title,
+        "original_path": original_path,
+        "size_bytes": size,
+        "mime_type": mime_type,
+    }

forge_mvc_audio-1.0.0b16/forge_mvc_audio/probe.py

@@ -0,0 +1,130 @@
+"""Extraction de métadonnées audio via ffprobe.
+
+``probe_audio`` lance ``ffprobe`` (lecture seule) sur une source et en extrait
+durée, codec, bitrate, sample rate et nombre de canaux. Sert aussi de
+**validation profonde** : un fichier sans flux audio (ou que ffprobe refuse) est
+rejeté — bien plus fiable que l'extension validée à l'upload.
+
+L'exécution de ffprobe est déléguée à un *runner* injectable → le parsing et la
+validation sont testables **sans ffprobe réel**. Invocation sûre : arguments en
+**liste** (jamais ``shell=True``), chemin en argument, timeout.
+
+Aucun ffmpeg lancé : ffprobe lit, ne transcode pas.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from forge_mvc_audio.config import AudioConfig, load_audio_config
+
+__all__ = ["AudioMetadata", "AudioProbeError", "probe_audio", "parse_probe_json"]
+
+# Un runner prend (ffprobe_bin, path) et retourne la sortie JSON de ffprobe.
+ProbeRunner = Callable[[str, str], str]
+
+_PROBE_TIMEOUT_SECONDS = 30
+
+
+class AudioProbeError(Exception):
+    """ffprobe a échoué, ou la source n'est pas un audio exploitable."""
+
+
+@dataclass(frozen=True)
+class AudioMetadata:
+    duration_seconds: int | None
+    audio_codec: str | None
+    bitrate_kbps: int | None
+    sample_rate_hz: int | None
+    channels: int | None
+    container: str | None
+
+
+def _default_runner(ffprobe_bin: str, path: str) -> str:
+    """Lance ffprobe et retourne sa sortie JSON (stdout)."""
+    import subprocess
+
+    cmd = [
+        ffprobe_bin,
+        "-v", "error",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        path,
+    ]
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=_PROBE_TIMEOUT_SECONDS
+        )
+    except FileNotFoundError as exc:
+        raise AudioProbeError(f"ffprobe introuvable : {ffprobe_bin}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise AudioProbeError("ffprobe a dépassé le délai") from exc
+    if result.returncode != 0:
+        raise AudioProbeError(
+            f"ffprobe a échoué (code {result.returncode}) : {result.stderr.strip()}"
+        )
+    return result.stdout
+
+
+def _int_or_none(value) -> int | None:
+    if value is None or str(value).strip() == "":
+        return None
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_probe_json(payload: str | dict) -> AudioMetadata:
+    """Parse la sortie ffprobe (``-print_format json``) en ``AudioMetadata``.
+
+    Lève ``AudioProbeError`` si la sortie est illisible ou sans flux audio.
+    """
+    data = json.loads(payload) if isinstance(payload, str) else payload
+    streams = data.get("streams", []) if isinstance(data, dict) else []
+    fmt = data.get("format", {}) if isinstance(data, dict) else {}
+
+    audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
+    if audio is None:
+        raise AudioProbeError("aucun flux audio détecté")
+
+    duration = fmt.get("duration") or audio.get("duration")
+    bitrate = fmt.get("bit_rate") or audio.get("bit_rate")
+    bitrate_kbps = _int_or_none(bitrate)
+    if bitrate_kbps is not None:
+        bitrate_kbps = bitrate_kbps // 1000
+
+    return AudioMetadata(
+        duration_seconds=_int_or_none(duration),
+        audio_codec=audio.get("codec_name"),
+        bitrate_kbps=bitrate_kbps,
+        sample_rate_hz=_int_or_none(audio.get("sample_rate")),
+        channels=_int_or_none(audio.get("channels")),
+        container=fmt.get("format_name"),
+    )
+
+
+def probe_audio(
+    path: str,
+    *,
+    config: AudioConfig | None = None,
+    runner: ProbeRunner | None = None,
+) -> AudioMetadata:
+    """Sonde ``path`` et retourne ses métadonnées (valide le flux + la durée)."""
+    cfg = config or load_audio_config()
+    run: ProbeRunner = runner or _default_runner
+
+    meta = parse_probe_json(run(cfg.ffprobe_bin, str(path)))
+
+    if (
+        cfg.max_duration_seconds
+        and meta.duration_seconds is not None
+        and meta.duration_seconds > cfg.max_duration_seconds
+    ):
+        raise AudioProbeError(
+            f"durée {meta.duration_seconds}s > maximum "
+            f"{cfg.max_duration_seconds}s (FORGE_AUDIO_MAX_DURATION_SECONDS)"
+        )
+    return meta

forge_mvc_audio-1.0.0b16/forge_mvc_audio/storage.py

@@ -0,0 +1,97 @@
+"""Disposition des fichiers audio sur disque — sans état.
+
+Le stockage est **uuid-based** : le nom de fichier fourni par l'utilisateur
+n'apparaît **jamais** dans le chemin (anti-traversal par construction). Seule
+l'extension, validée contre une liste blanche, est conservée.
+
+Disposition (sous ``FORGE_AUDIO_STORAGE_ROOT``), **non partitionnée par date**
+pour permettre le lookup par ``uuid`` seul (pas de base de données) :
+
+    originals/<uuid>/source<ext>
+    transcoded/<uuid>/audio.mp3
+
+Le lookup de lecture (``resolve_playable_relpath``) cherche d'abord le MP3
+transcodé, puis la source — uniquement à l'intérieur du dossier de l'``uuid``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from uuid import UUID
+
+__all__ = [
+    "ALLOWED_EXTENSIONS",
+    "safe_extension",
+    "is_valid_uuid",
+    "original_relpath",
+    "transcoded_relpath",
+    "store_original",
+    "resolve_playable_relpath",
+]
+
+# Conteneurs/formats audio acceptés en entrée. La sortie de transcodage est MP3.
+ALLOWED_EXTENSIONS = frozenset({".mp3", ".wav", ".ogg", ".flac", ".m4a", ".aac"})
+
+
+def safe_extension(filename: str) -> str:
+    """Extension en minuscules du nom fourni (``""`` si aucune)."""
+    return Path(filename or "").suffix.lower()
+
+
+def is_valid_uuid(value: str) -> bool:
+    """Vrai si ``value`` est un UUID canonique (clé de lookup sûre)."""
+    try:
+        return str(UUID(str(value))) == str(value).lower()
+    except (ValueError, AttributeError, TypeError):
+        return False
+
+
+def original_relpath(uuid: str, ext: str) -> str:
+    """Chemin relatif de la source, uuid-based."""
+    return f"originals/{uuid}/source{ext}"
+
+
+def transcoded_relpath(uuid: str) -> str:
+    """Chemin relatif du MP3 transcodé, uuid-based."""
+    return f"transcoded/{uuid}/audio.mp3"
+
+
+def store_original(
+    data: bytes, uuid: str, ext: str, *, storage_root: str
+) -> str:
+    """Écrit la source à un emplacement uuid-based ; retourne le chemin relatif.
+
+    L'``uuid`` est validé avant toute construction de chemin : il apparaît dans
+    l'arborescence (``originals/<uuid>/``), donc un uuid non canonique fourni par
+    l'appelant serait un vecteur de traversal à l'écriture. La symétrie avec
+    ``resolve_playable_relpath`` (qui valide en lecture) est ainsi garantie.
+    """
+    if not is_valid_uuid(uuid):
+        raise ValueError(f"uuid audio invalide (anti-traversal) : {uuid!r}")
+    rel = original_relpath(uuid, ext)
+    target = Path(storage_root) / rel
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(data)
+    return rel
+
+
+def resolve_playable_relpath(uuid: str, *, storage_root: str) -> str | None:
+    """Retrouve le fichier lisible pour ``uuid`` (sans base de données).
+
+    Préfère le MP3 transcodé s'il existe, sinon la source d'origine. Retourne le
+    chemin **relatif** (sous ``storage_root``) ou ``None`` si rien n'est trouvé.
+    Refuse tout ``uuid`` qui n'est pas un UUID canonique (anti-traversal).
+    """
+    if not is_valid_uuid(uuid):
+        return None
+    root = Path(storage_root)
+
+    transcoded = transcoded_relpath(uuid)
+    if (root / transcoded).is_file():
+        return transcoded
+
+    source_dir = root / "originals" / uuid
+    if source_dir.is_dir():
+        for entry in sorted(source_dir.glob("source.*")):
+            if entry.is_file():
+                return f"originals/{uuid}/{entry.name}"
+    return None

forge_mvc_audio-1.0.0b16/forge_mvc_audio/transcode.py

@@ -0,0 +1,84 @@
+"""Runner ffmpeg : transcodage MP3.
+
+Construit et exécute la commande ffmpeg du profil MP3 standard Forge Audio. Le
+constructeur de commande est **pur** (testable sans ffmpeg) ; l'exécution est
+déléguée à un *runner* injectable.
+
+Sécurité d'invocation :
+- arguments en **liste** (jamais ``shell=True``) → aucune injection ;
+- chemins passés en arguments (le caller fournit des chemins uuid-based,
+  jamais le nom de fichier utilisateur) ;
+- ``timeout`` obligatoire (un ffmpeg sans borne peut tourner indéfiniment).
+
+Profil MP3 standard :
+
+    -c:a libmp3lame -b:a 192k -ac 2
+    -map_metadata -1   (retire les métadonnées d'origine)
+    -vn                (ignore toute piste vidéo/pochette → audio pur)
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+
+__all__ = [
+    "FfmpegError",
+    "DEFAULT_TRANSCODE_TIMEOUT",
+    "build_transcode_command",
+    "transcode_to_mp3",
+]
+
+# Un runner prend (cmd, timeout) et retourne (returncode, stderr).
+FfmpegRunner = Callable[[list[str], int], tuple[int, str]]
+
+DEFAULT_TRANSCODE_TIMEOUT = 1800  # 30 min — borne haute d'un transcodage audio
+
+
+class FfmpegError(Exception):
+    """ffmpeg a échoué, est absent, ou a dépassé le délai."""
+
+
+def build_transcode_command(
+    ffmpeg_bin: str, input_path: str, output_path: str, *, bitrate_kbps: int = 192
+) -> list[str]:
+    """Commande de transcodage MP3 (libmp3lame, stéréo, sans métadonnées)."""
+    return [
+        ffmpeg_bin,
+        "-y",
+        "-i", input_path,
+        "-vn",
+        "-c:a", "libmp3lame", "-b:a", f"{bitrate_kbps}k", "-ac", "2",
+        "-map_metadata", "-1",
+        output_path,
+    ]
+
+
+def _default_ffmpeg_runner(cmd: list[str], timeout: int) -> tuple[int, str]:
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout
+        )
+    except FileNotFoundError as exc:
+        raise FfmpegError(f"ffmpeg introuvable : {cmd[0]}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise FfmpegError(f"ffmpeg a dépassé le délai ({timeout}s)") from exc
+    return result.returncode, result.stderr
+
+
+def transcode_to_mp3(
+    input_path: str,
+    output_path: str,
+    *,
+    ffmpeg_bin: str = "ffmpeg",
+    bitrate_kbps: int = 192,
+    runner: FfmpegRunner | None = None,
+    timeout: int = DEFAULT_TRANSCODE_TIMEOUT,
+) -> None:
+    """Transcode ``input_path`` en MP3 standard à ``output_path``."""
+    cmd = build_transcode_command(
+        ffmpeg_bin, input_path, output_path, bitrate_kbps=bitrate_kbps
+    )
+    code, stderr = (runner or _default_ffmpeg_runner)(cmd, timeout)
+    if code != 0:
+        raise FfmpegError(f"ffmpeg a échoué (code {code}) : {stderr.strip()}")

forge_mvc_audio-1.0.0b16/forge_mvc_audio.egg-info/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: forge-mvc-audio
+Version: 1.0.0b16
+Summary: Forge Audio — module opt-in pour l'upload, le sondage de métadonnées (ffprobe), le transcodage MP3 (ffmpeg) et la lecture audio en streaming (HTTP Range). Sans état : aucune base de données. Worker CLI forge audio:doctor.
+Author: Roger Lequette
+License-Expression: LicenseRef-Forge-Proprietary
+Project-URL: Homepage, https://github.com/caucrogeGit/Forge
+Project-URL: Repository, https://github.com/caucrogeGit/Forge
+Project-URL: Documentation, https://forgemvc.com/docs/forge/audio/
+Keywords: python,mvc,forge,audio,ffmpeg,mp3,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: forge-mvc<2,>=1.0.0b16
+Dynamic: license-file
+
+# forge-mvc-audio
+
+Module **opt-in** Forge pour la gestion audio : upload, sondage de métadonnées,
+transcodage MP3 et lecture en streaming. **Sans état** (aucune base de données).
+
+## Statut : Beta — opt-in officiel
+
+`forge-mvc-audio` fournit une chaîne audio complète et **sobre**, calquée sur
+`forge-mvc-video` mais **sans la machinerie à état** (pas de table SQL, pas de
+suivi de jobs, pas de file de transcodage). C'est un choix délibéré : les
+opérations audio sont synchrones et la lecture retrouve les fichiers par `uuid`
+sur le disque.
+
+> **ffmpeg / ffprobe** sont des binaires **système** (pas des dépendances pip).
+> Le module se branche sans eux (le service de lecture fonctionne), mais le
+> sondage exige `ffprobe` et le transcodage exige `ffmpeg`.
+> `forge audio:doctor` signale leur absence.
+
+Installation (mode éditable depuis les sources) :
+
+```bash
+pip install -e packages/forge-mvc-audio/
+```
+
+## Ce que contient le module
+
+- `config` — `AudioConfig` + `load_audio_config()` (configuration depuis
+  `FORGE_AUDIO_*`, valeurs par défaut sûres).
+- `storage` — disposition **uuid-based** des fichiers (le nom utilisateur
+  n'apparaît jamais dans le chemin → anti-traversal par construction).
+- `probe` — `probe_audio()` via `ffprobe` : durée, codec, bitrate, sample rate,
+  nombre de canaux, conteneur. Sert aussi de validation profonde (rejet d'un
+  fichier sans flux audio).
+- `ingest` — `ingest_audio(data, filename)` : valide (taille, extension), stocke
+  la source, retourne un enregistrement (`uuid`, chemin, taille, MIME).
+- `transcode` — `transcode_to_mp3()` via `ffmpeg` (profil MP3 192 kbps, stéréo,
+  métadonnées d'origine retirées). Constructeurs de commande **purs**, runner
+  injectable (testable sans ffmpeg).
+- `http` — `register_audio_routes(router)` : route `GET /audio/{uuid}` servie en
+  **streaming HTTP Range** (seek), Bearer token optionnel
+  (`FORGE_AUDIO_API_TOKEN`).
+- `cli.doctor` — `forge audio:doctor` : diagnostic statique (package, config,
+  ffprobe, ffmpeg, routes).
+
+## Formats acceptés à l'upload
+
+`mp3`, `wav`, `ogg`, `flac`, `m4a`, `aac`. La sortie de transcodage est MP3.
+
+## Sécurité
+
+- Invocation `ffmpeg`/`ffprobe` en **liste d'arguments** (jamais `shell=True`).
+- Chemins **uuid-based** : le `uuid` de l'URL n'est qu'une clé de lookup, validée
+  comme un UUID — aucun *path traversal*.
+- Token Bearer optionnel sur la route de lecture (mode local ouvert par défaut).
+- L'auth vit dans ce module, **jamais** dans Forge Core.
+
+## Configuration (`FORGE_AUDIO_*`)
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `FORGE_AUDIO_FFMPEG_BIN` | `ffmpeg` | binaire ffmpeg |
+| `FORGE_AUDIO_FFPROBE_BIN` | `ffprobe` | binaire ffprobe |
+| `FORGE_AUDIO_STORAGE_ROOT` | `storage/audio` | racine de stockage |
+| `FORGE_AUDIO_MAX_UPLOAD_MB` | `200` | taille max d'upload |
+| `FORGE_AUDIO_MAX_DURATION_SECONDS` | `7200` | durée max (2 h) |
+| `FORGE_AUDIO_API_TOKEN` | *(absent)* | Bearer token de lecture (optionnel) |

forge_mvc_audio-1.0.0b16/forge_mvc_audio.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+forge_mvc_audio/__init__.py
+forge_mvc_audio/config.py
+forge_mvc_audio/http.py
+forge_mvc_audio/ingest.py
+forge_mvc_audio/probe.py
+forge_mvc_audio/storage.py
+forge_mvc_audio/transcode.py
+forge_mvc_audio.egg-info/PKG-INFO
+forge_mvc_audio.egg-info/SOURCES.txt
+forge_mvc_audio.egg-info/dependency_links.txt
+forge_mvc_audio.egg-info/requires.txt
+forge_mvc_audio.egg-info/top_level.txt
+forge_mvc_audio/cli/__init__.py
+forge_mvc_audio/cli/doctor.py

forge_mvc_audio-1.0.0b16/forge_mvc_audio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forge_mvc_audio-1.0.0b16/forge_mvc_audio.egg-info/requires.txt

@@ -0,0 +1 @@
+forge-mvc<2,>=1.0.0b16

forge_mvc_audio-1.0.0b16/forge_mvc_audio.egg-info/top_level.txt

@@ -0,0 +1 @@
+forge_mvc_audio

forge_mvc_audio-1.0.0b16/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forge-mvc-audio"
+version = "1.0.0b16"
+description = "Forge Audio — module opt-in pour l'upload, le sondage de métadonnées (ffprobe), le transcodage MP3 (ffmpeg) et la lecture audio en streaming (HTTP Range). Sans état : aucune base de données. Worker CLI forge audio:doctor."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.12"
+authors = [
+    { name = "Roger Lequette" },
+]
+license = "LicenseRef-Forge-Proprietary"
+keywords = ["python", "mvc", "forge", "audio", "ffmpeg", "mp3", "streaming"]
+dependencies = [
+    "forge-mvc>=1.0.0b16,<2",
+]
+# NB : ffmpeg/ffprobe sont des binaires SYSTÈME, pas des dépendances pip.
+# Le module se branche sans eux (mode serveur de fichiers / probe indisponible),
+# mais `forge audio:doctor` signale leur absence ; le transcodage les exige.
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/caucrogeGit/Forge"
+Repository = "https://github.com/caucrogeGit/Forge"
+Documentation = "https://forgemvc.com/docs/forge/audio/"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["forge_mvc_audio*"]

forge_mvc_audio-1.0.0b16/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+