# Wallpaper EQ Generator Codex Handoff

Updated: 2026-05-19

This is the handoff brief for the audio-reactive wallpaper generator. It should give a future Codex session enough context to continue development without rediscovering the project from scratch.

## Product

Wallpaper EQ Generator creates YouTube-ready and wallpaper-style MP4 videos from a wallpaper image or video plus a music track. The current desktop app focuses on an EQ visualizer with optional transparent item sprites that collide with the generated bars through a physics simulation.

The current web studio is a lighter browser version for quick preview/export experiments. The desktop app is the source of truth for the full wizard, hitbox editing, FFmpeg export, and QA gate.

## Local Project

- Repo path: `/Users/jason/Projects/wallpaper-eq-studio`
- Cloudflare Pages project: `wallpaper-eq-studio`
- Hosted site: `https://wallpaper-eq-studio.pages.dev`
- Node requirement: Node.js 22 or newer
- External desktop export requirement: `ffmpeg` and `ffprobe` must be available on PATH

## Workspace Layout

- `apps/desktop`: Electron + React desktop app, wizard UI, IPC layer, FFmpeg generation pipeline
- `apps/web`: browser web studio
- `packages/types`: shared project, generation, QA, and media contracts
- `packages/engine`: shared audio analysis, bar frame generation, hitbox extraction, physics simulation, and canvas drawing
- `docs`: handoff and product planning docs
- `site`: Cloudflare Pages static site output
- `scripts/prepare-site-assets.mjs`: copies the web studio, docs, icon, source ZIP, and chunked Windows release into `site`

## Current Desktop Flow

1. Select wallpaper media. Supported wallpaper inputs include images and videos.
2. Select a music track.
3. Configure equalizer settings.
4. Add transparent item sprites.
5. Auto-detect and edit hitboxes.
6. Tune per-item physics.
7. Generate preview/proxy.
8. Pass QA, then export final MP4.

Final export is intentionally blocked until QA passes. QA checks include duration, frame count, black-frame ratio, audio peak, and audio/video stream duration sanity.

## Build And Verification Commands

```bash
cd /Users/jason/Projects/wallpaper-eq-studio
npm test
npm run build:web
npm run package:win --workspace @wallpaper-eq/desktop
zip -qr apps/desktop/release/wallpaper-eq-generator-source-v0.1.0.zip . -x "node_modules/*" "*/node_modules/*" "site/*" "output/*" ".playwright-cli/*" "apps/desktop/release/*" "apps/desktop/build/electron-dist/*" "apps/desktop/build/package-stages/*" "apps/desktop/dist-electron/*" "apps/desktop/dist-renderer/*" "apps/web/dist/*" "packages/*/dist/*" ".git/*" ".DS_Store"
node scripts/prepare-site-assets.mjs
npx wrangler pages deploy site --project-name wallpaper-eq-studio
```

## Current Release Artifact

- Windows artifact: `apps/desktop/release/Wallpaper EQ Generator-win-x64.zip`
- Windows size: about 152 MiB
- Windows SHA-256: `de5f2f03cbb224013631f91544f141107edeb617a3fd355a322cd3ff27871730`
- Website manifest: `/downloads/wallpaper-eq-generator-windows-x64.manifest.json`
- Source ZIP: `/downloads/wallpaper-eq-generator-source-v0.1.0.zip`

The Windows app is currently unsigned. On Windows, SmartScreen may warn on first launch.

## Important Implementation Files

- `apps/desktop/src/App.tsx`: desktop wizard and UI state
- `apps/desktop/electron/ipc.ts`: native IPC handlers and file pickers
- `apps/desktop/electron/services/generationService.ts`: main desktop generation orchestration
- `apps/desktop/electron/services/composer.ts`: FFmpeg argument generation
- `apps/desktop/electron/services/frameRenderer.ts`: frame rendering and compositing helpers
- `apps/desktop/electron/services/qa.ts`: QA gate checks
- `packages/engine/src/audio/barAnalysis.ts`: FFT/bar analysis
- `packages/engine/src/render/drawFrame.ts`: shared overlay renderer
- `packages/engine/src/physics/simulate.ts`: Rapier physics simulation
- `packages/types/src/index.ts`: shared contracts

## Next Product Direction

The next version should become an Ultimate Wallpaper Generator launcher. The launcher should select and launch different generator modes while sharing one media library, project format, audio analysis system, render pipeline, and export queue.

Proposed first modes:

- Core EQ Mode: current generic EQ/bar/physics workflow.
- Porter Robinson-inspired Mode: original fan-made low-poly/nature/digital-scribble/ethereal overlays, not official art.
- Sewerslvt/glitchbreak-inspired Mode: original fan-made dark Y2K/glitch/anime-adjacent breakbeat overlays, not official art.

See `docs/ultimate-wallpaper-generator-roadmap.md` for the mode architecture and style notes.

## Rights And Asset Rule

Do not bundle official artist artwork, logos, album covers, music videos, or copyrighted visuals unless the user provides assets they are allowed to use. The artist modes should be original, fan-made style packs inspired by visual language, not copies.

## Known Gaps

- The Windows ZIP depends on external FFmpeg and FFprobe commands being installed on PATH.
- The desktop app is unsigned.
- The web studio is useful for preview-style workflows but does not replace the desktop export pipeline.
- MP4-as-input with audio extraction is partially aligned with current wallpaper video support, but the future mode system should formalize a single "media source with audio" path.