100 lines
5.2 KiB
Markdown
100 lines
5.2 KiB
Markdown
# #109 — Support audio & vidéo (lecteurs HTML5 intégrés)
|
||
|
||
> **Version livrée :** 2.18.0 · **Statut :** ✅ · **Impact :** 🟡
|
||
> **Zone :** backend (`main`, `indexer`, `media_types`, `bookslm`) + frontend
|
||
> (`viewer.js`, `utils.js`, `style.css`, `sw.js`).
|
||
|
||
## Contexte
|
||
|
||
Le socle média de #108 (`backend/media_types.py`) exposait déjà
|
||
`AUDIO_EXTENSIONS` / `VIDEO_EXTENSIONS`, mais ces fichiers n'étaient ni indexés
|
||
ni affichables : ils tombaient dans le chemin binaire « Ce fichier est binaire
|
||
et ne peut pas être affiché » + bouton download.
|
||
|
||
## Ce qui a été livré
|
||
|
||
### A. Backend
|
||
|
||
- **Indexation** : `AUDIO_EXTENSIONS` et `VIDEO_EXTENSIONS` sont intégrées à
|
||
`SUPPORTED_EXTENSIONS` (`indexer.py`). La branche `is_media(ext)` existante
|
||
indexe **nom / taille / mtime** sans jamais lire les octets (`content: ""`),
|
||
donc le TF-IDF et les logs restent propres. Le watcher et le filtre `ext:`
|
||
suivent automatiquement.
|
||
- **Streaming** : le helper Range de `pdf/stream` a été extrait en
|
||
`_stream_file_with_range(file_path, request, media_type)` (206 +
|
||
`Content-Range` + `Accept-Ranges`, `416` sur plage invalide, `FileResponse`
|
||
simple sinon, lectures offloadées via `asyncio.to_thread`). `pdf/stream`
|
||
l'utilise désormais aussi (comportement inchangé, tests de régression).
|
||
- **Nouvel endpoint `GET /api/media/{vault}?path=…`** : sert audio/vidéo avec le
|
||
MIME `media_types.media_mime_type` (surcharges `.m4a→audio/mp4`,
|
||
`.opus/.oga→audio/ogg`, `.mov→video/quicktime`, `.m4v→video/mp4`).
|
||
- **Gardes-fous** : `_resolve_safe_path`, `check_vault_access`, et
|
||
`OBSIGATE_MEDIA_MAX_INLINE_MB` (défaut **500 Mo**) — au-delà, l'endpoint
|
||
renvoie `413` et la vue fichier bascule sur l'UI de téléchargement.
|
||
- **`api_file_view()`** renvoie, avant tout `read_text()`, `is_audio` /
|
||
`is_video` / `stream_url` / `media_mime` / `size_bytes`. Au-delà de la limite :
|
||
`unsupported: true` + `media_too_large: true`.
|
||
|
||
### B/C. Frontend — lecteurs
|
||
|
||
- `viewer.js` dispatche `data.is_audio` → `renderAudioViewer()` et
|
||
`data.is_video` → `renderVideoViewer()`.
|
||
- **Audio** : `<audio controls preload="metadata">` pleine largeur, artwork
|
||
placeholder (icône Lucide `audio-lines`), durée lue via `loadedmetadata`,
|
||
toolbar (titre, voûte + taille, badge durée, ouvrir l'original, télécharger).
|
||
- **Vidéo** : `<video controls playsinline preload="metadata">` centrée sur une
|
||
scène noire letterboxée (`max-height: calc(100vh - 180px)`), même toolbar
|
||
avec durée + résolution.
|
||
- `renderMediaFallback()` : sur l'événement `error` de l'élément média (codec
|
||
hors web-natif : `.mkv`, `.avi`, HEVC…) ou si le fichier est trop volumineux,
|
||
remplace le lecteur par l'UI binaire + message
|
||
`viewer.media_unsupported` / `viewer.media_too_large` + **Télécharger** /
|
||
**Ouvrir dans un nouvel onglet**.
|
||
- **Pause** au changement de vue : `_mediaViewerCleanup` met en pause et détache
|
||
la source quand `renderFile()` re-rend la zone (changement d'onglet, navigation)
|
||
— pas de lecture persistante en v1 (cohérence #75).
|
||
- `EXT_ICONS` (`utils.js`) : audio → `audio-lines`, vidéo → `video`.
|
||
- i18n FR/EN (`viewer.media_unsupported`, `viewer.media_too_large`).
|
||
|
||
### D. Recherche & intégrations
|
||
|
||
- Filtres `ext:mp3`, `ext:mp4`, etc. opérationnels (les médias entrent dans
|
||
l'index).
|
||
- Récents / dashboards : previews vides (aucun texte extrait) — comportement
|
||
naturel de la branche binaire.
|
||
- **BooksLM** : `_file_entry()` ignore désormais tout média (`is_media`) — les
|
||
octets ne sont jamais envoyés au modèle ; les images restent gérées à part via
|
||
`load_vault_image_data_url` (vision).
|
||
- **Hors scope v1** (porte notée) : transcription audio via Whisper.
|
||
|
||
### E. Mobile & PWA
|
||
|
||
- Le service worker ne met **jamais** en cache le flux média
|
||
(`/api/media/{vault}`), tout en conservant le cache des miniatures
|
||
(`/api/media/{vault}/thumb`) et la stratégie Network First pour le reste. Les
|
||
requêtes `Range` étaient déjà exclues.
|
||
|
||
### F. Tests
|
||
|
||
- `tests/test_media_stream.py` : 206 + `Content-Range` + 1024 octets, `416` hors
|
||
borne, `200` + `Accept-Ranges` sans Range, suffix range, `413` au-delà de la
|
||
limite, `403` path traversal, `403` vault sans accès, `400` non-média, MIME
|
||
`.mov`, régression `pdf/stream`.
|
||
- `tests/test_media_indexing.py` : `.mp3`/`.mp4`/`.flac` dans l'arborescence et
|
||
l'index, `content == ""`, watcher pertinent, filtre `ext:mp3`.
|
||
- `tests/frontend/media-viewer.test.mjs` : helpers purs (`formatMediaDuration`,
|
||
`buildMediaUrl`) + vérifications statiques (dispatch, `<audio>`/`<video>`,
|
||
fallback, CSS, icônes, i18n, service worker, endpoints backend).
|
||
- `tests/e2e/media-viewer.spec.js` : lecture `<audio>` et `<video>` via
|
||
`/api/media` + réponse `206` sur requête `Range`. Fixtures :
|
||
`test_vault/sample-audio.mp3` (sine 1 s) et `test_vault/sample-video.webm`
|
||
(VP8 64×64).
|
||
|
||
## Limitations connues
|
||
|
||
- Formats hors web-natifs (`.mkv`, `.avi`, HEVC, AC-4) : non lisibles sans
|
||
transcodage (ffmpeg hors scope) → repli téléchargement / lecteur de l'OS.
|
||
- HLS, sous-titres `<track src=".vtt">` et vignettes vidéo : hors scope v1.
|
||
- Gros médias (> 500 Mo par défaut) : pas de lecture intégrée (protège le worker
|
||
uvicorn unique) ; ajustable via `OBSIGATE_MEDIA_MAX_INLINE_MB`.
|