odysseus/docs/discovery/domains/media.md

Media

Features in this document are generated from ../feature-catalog.json, the canonical inventory.

MEDIA-001 — Gallery Image Library & Album Operations

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Organizes images into custom albums, provides grid browsing, tagging, and album metadata management.

Evidence summary

• routes/gallery/gallery_routes.py — @router.get('/api/gallery/library') — Fetches image library list with tag filters.
• static/js/gallery.js — initGallery — Main gallery grid renderer and uploader.

Unknowns

• Thumbnail generation overhead for high-resolution RAW camera images.

MEDIA-002 — Image Processing, AI Upscaling & Style Transfer

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Executes local image enhancement, background removal, face sharpening, and AI upscaling operations.

Evidence summary

• routes/gallery/gallery_routes.py — @router.post('/api/gallery/ai-upscale') — Runs RealESRGAN image upscaling.
• routes/gallery/gallery_routes.py — @router.post('/api/image/remove-bg') — Executes background removal pass.

Unknowns

• High GPU memory allocation when upscaling 4K images.

MEDIA-003 — Interactive Image Canvas Editor & Persisted Drafts

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Provides full multi-layer raster canvas editor, brush tools, transforms, masks, and draft project persistence.

Evidence summary

• routes/editor_draft_routes.py — setup_editor_draft_routes — API routes for saving and loading canvas project drafts.
• static/js/editor/history-panel.js — HistoryManager — Canvas undo/redo stack manager.

Unknowns

• Browser memory leak if multi-gigabyte layer undo buffers are kept indefinitely.

MEDIA-004 — Text-to-Speech (TTS) Synthesis Service

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Synthesizes spoken audio from text using local Kokoro, EdgeTTS, or OpenAI TTS engines.

Evidence summary

• routes/tts_routes.py — @router.post('/synthesize') — Synthesizes TTS audio clip.
• services/tts/tts_service.py — TTSService — Provider abstraction layer for audio speech generation.

Unknowns

• Audio synthesis latency on CPU-only hardware setups.

MEDIA-005 — Speech-to-Text (STT) Audio Transcription Service

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Transcribes user audio recordings into text using faster-whisper or local speech models.

Evidence summary

• routes/stt_routes.py — @router.post('/transcribe') — Accepts multipart audio file and returns transcription text.
• services/stt/stt_service.py — STTService — Whisper audio transcription engine wrapper.

Unknowns

• Missing ffmpeg system dependency prevents audio format decoding.

MEDIA-006 — Digital Signature Stamp Storage & Placement

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Stores transparent PNG user signatures and stamps for placement onto PDF forms and documents.

Evidence summary

• routes/signature_routes.py — setup_signature_routes — CRUD endpoints for managing user signature PNG stamps.

Unknowns

• Cross-site scripting if signature image titles contain unescaped user input.

MEDIA-007 — Generated Image Artifact Route & MCP Integration

• Domain: media
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Serves generated AI artwork artifacts and integrates with image generation MCP server.

Evidence summary

• app.py — serve_generated_image — Serves generated image artifacts with cache headers.
• src/generated_images.py — resolve_generated_image_path — Confines requested image path within artifacts directory.

Unknowns

• Path traversal vulnerability if filename parameter is un-sanitized.

MEDIA-008 — Native MLX Image Bridge (macOS Apple Silicon)

• Domain: media
• Status: experimental
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: pending — Requires Apple Silicon, macOS tooling, and the compiled MLX bridge.

Purpose

Native Apple Swift bridge for hardware-accelerated diffusion and MLX image colorization on macOS.

Evidence summary

• swift/odysseus-mlx-image-bridge/Package.swift — Package — Swift package manifest for native MLX image bridge.
• scripts/mlx_image_server.py — main — Python daemon wrapping native Swift MLX binary.

Unknowns

• Binary build requires Xcode command line tools build step (build-macos-app.sh).