docs/LINUX_VIDEO_EXPORT_ANALYSIS.md

# Linux Video Export Analysis

## Scope
This analysis traces how MP4 export behaves on Linux hosts and where failures are surfaced.

## Current behavior summary
- The backend now supports a dual-path export engine in `backend/src/video_engine.py`:
  - **Windows:** COM-based PowerPoint export.
  - **Linux/macOS:** MoviePy + ffmpeg export from screenshots.
- A hard platform guard still exists in the legacy `/generate` SSE route (`backend/routes/generate.py`) that blocks `output_format=video` on non-Windows.
- The newer run-based routes in `backend/routes/runs.py` use `VideoStudio.build_video(...)` and can export MP4 on Linux when MoviePy and ffmpeg are available.

## Detailed code-path findings

### 1) Linux-capable engine exists
`VideoStudio` explicitly selects a MoviePy/ffmpeg path for non-Windows hosts and documents Linux/macOS behavior in module docs and runtime branches.

Operational impact:
- Linux MP4 export **is architecturally supported** in the engine layer.
- If ffmpeg or MoviePy is unavailable, the engine raises `MovieEngineUnavailableError` with install guidance.

### 2) Legacy route still blocks Linux video output
In `backend/routes/generate.py`, a platform check rejects `video`/`pptx` output when host OS is not Windows.

Operational impact:
- Any client still using `/generate` cannot export video on Linux, regardless of the new engine.
- Error messaging is explicit and currently advises users to switch formats.

### 3) Run-based API supports Linux video export
`backend/routes/runs.py` calls shared `_run_powerpoint_export(...)`, which delegates to `VideoStudio.build_video(...)`. On Linux this resolves to the MoviePy path rather than COM.

Operational impact:
- Clients using `/runs/text-to-video` and `/runs/screenshots-to-video` can produce MP4 on Linux if prerequisites exist.

### 4) Host dependency gap (ffmpeg)
The Linux path depends on ffmpeg and MoviePy. ffmpeg is not installed in this environment (verified previously in shell), so Linux export would fail at runtime with `MovieEngineUnavailableError`.

Operational impact:
- Feature can appear “broken” even though code path is present.
- This is an environment/package issue, not strictly a routing/logic defect.

## Risk/consistency assessment

1. **API inconsistency risk:**
   - `/generate` (legacy) blocks Linux video.
   - `/runs/*` (new) allows Linux video.
   This can produce contradictory UX depending on which frontend flow is used.

2. **Operational readiness risk:**
   - Linux deploys missing ffmpeg will fail exports late unless preflight checks are surfaced in UI.

3. **Documentation drift risk:**
   - High-level docs still emphasize Windows-only PowerPoint export; this may obscure the newer Linux-capable MoviePy path.

## Recommended actions

### High priority
1. **Unify behavior across endpoints:**
   - Either migrate all video workflows to `/runs/*` exclusively, or remove/update the non-Windows block in `/generate` so it delegates to `VideoStudio` like run routes.

2. **Add explicit backend preflight endpoint/flag:**
   - Return capability matrix (e.g., `can_export_video`, `missing_dependencies: [ffmpeg, moviepy]`) so frontend can disable/guide before launch.

3. **Install ffmpeg in Linux runtime images:**
   - Ensure container/VM provisioning includes ffmpeg package.

### Medium priority
4. **Route deprecation plan:**
   - Mark `/generate` as legacy and direct UI to run-based routes to avoid split behavior.

5. **Docs refresh:**
   - Update README/backend docs to clarify:
     - PPTX generation remains Windows+PowerPoint.
     - MP4 export is cross-platform via MoviePy+ffmpeg (where available).

## Validation checklist for Linux
- Confirm `ffmpeg` is installed and executable.
- Confirm `moviepy>=2.0` is installed.
- Run one export through `/runs/text-to-video` with `output_format=video`.
- Verify final `video_file` exists and is non-zero in output metadata.
- Confirm frontend uses run-based endpoints for video export paths.