-
Notifications
You must be signed in to change notification settings - Fork 0
architecture
Design decisions for bananascaler.
A 3-stage sequential pipeline coordinated by a Go CLI with a Bubbletea TUI:
- Extract — FFmpeg decodes source video to JPEG frames.
- Upscale — Real-ESRGAN (ncnn-vulkan) applies neural super-resolution per frame.
- Re-encode — FFmpeg re-assembles frames + muxes original audio → atomic rename.
Status: Accepted
Date: 2026-07-16
Frame extraction produces thousands of intermediate images. PNG (lossless) is the naive choice but generates 3–5× more disk I/O than JPEG.
Use JPEG at -q:v 2 (near-lossless). Real-ESRGAN input quality at this level introduces no perceptible difference in the upscaled output.
-
Positive: ~60–70% reduction in
/tmp/disk usage; lower I/O pressure on NVMe storage. - Negative: Technically lossy intermediate. Unacceptable for archival workflows requiring pixel-perfect round-trips.
Status: Accepted
Date: 2026-07-16
Real-ESRGAN offers both a CUDA-only binary and an ncnn-Vulkan binary. CUDA requires NVIDIA; Vulkan runs on NVIDIA, AMD, and Intel Arc.
Use realesrgan-ncnn-vulkan. GPU vendor portability outweighs any CUDA-specific optimizations.
- Positive: Works on any Vulkan-capable GPU, including iGPUs.
- Negative: ncnn may be slightly slower than native CUDA on high-end NVIDIA cards.
Status: Accepted
Date: 2026-07-16
A multi-hour encode interrupted at 99% leaves a corrupt file that passes size checks and silently deceives the user.
Encode to output.mp4.tmp. Rename to output.mp4 only on exit code 0.
-
Positive: Interrupted runs always leave either a valid output or a clearly-named
.tmpartifact. -
Negative: Requires disk space for both
.tmpand final file simultaneously during the rename moment (negligible: rename is instantaneous on same filesystem).
Status: Accepted
Date: 2026-07-16
The pipeline needs to display progress and log messages, but the output method varies: interactive TUI in terminals, plain text when piped, and potentially programmatic consumers in the future.
Define a pipeline.Logger interface with methods Info, OK, Warn, Step, Err, and Progress. The pipeline accepts this interface in Run() and never writes to stdout/stderr directly.
- Positive: Pipeline is fully decoupled from output. TUI, plain text, or test mocks can all consume pipeline events.
- Negative: Slight overhead from interface method calls (negligible for this use case).
Status: Accepted
Date: 2026-07-16
A 3-stage pipeline running for minutes to hours needs real-time feedback. A static progress bar is insufficient for showing multiple stages, logs, and system info simultaneously.
Use Charm's Bubbletea framework for an interactive TUI dashboard. Auto-detect TTY via term.IsTerminal(): if stdout is a terminal, launch TUI; otherwise fall back to plain text. Add --no-tui flag for explicit opt-out.
- Positive: Rich, real-time dashboard with stage tracking, progress bars, and scrollable logs. Graceful degradation to plain text.
- Negative: Adds ~800KB to binary size (5.0MB total). Requires terminal for full experience.
Status: Accepted
Date: 2026-07-16
The original Bash script (bananascaler.sh) works but lacks structured error handling, progress reporting, and a TUI. Bash limitations make it difficult to add features like parallel processing or programmatic APIs.
Rewrite in Go with idiomatic project layout (cmd/, internal/). Preserve the same pipeline logic and engineering patterns (atomic output, session isolation, hardware detection).
- Positive: Structured error handling, interfaces for extensibility, Bubbletea TUI, proper signal handling, and a path to parallel processing.
- Negative: Requires Go compiler for building. Binary is larger than a script. Bash version retained for reference.
Status: Accepted
Date: 2026-07-16
The pipeline used hardcoded parameters (tile size 400, JPEG quality 2, no NVENC preset, x265 medium/CRF22) regardless of GPU capability. This caused SEGV crashes when the profile system (added in v0.4.0) paired heavier Real-ESRGAN models with large tiles on GPUs with insufficient VRAM (e.g., x4plus-anime + tile=400 on GTX 1060 6GB).
Introduce a 4-tier × 3-preset profile matrix stored in hardware/profile.go:
| Tier | VRAM | Example GPUs |
|---|---|---|
| low-end | ≤4 GB | GTX 1050 Ti, GTX 1650, RX 570 |
| mid-range | 4–8 GB | GTX 1060 6GB, RTX 2060, RX 5700 XT |
| high-end | ≥8 GB | RTX 3080, RTX 4090, RX 6800 XT |
| unknown | no NVIDIA | CPU-only / iGPU |
Each tier defines 3 presets (fast / balanced / quality) controlling:
- Tile size — VRAM-proportional, model-weight-aware
-
Model — lightweight (
animevideov3-x2) for small VRAM, heavy (x4plus) for large - JPEG quality — intermediate frame compression
- NVENC preset — p1 (fastest) to p7 (best quality)
- x265 preset/CRF — CPU fallback encoding
- Max scale — cap on upscale factor
Tile/model pairing rules (empirical):
-
animevideov3-x2(lightweight): safe up to tile 400 on 4GB -
x4plus-anime(medium): safe up to tile 200 on 6GB, tile 400 on 10GB -
x4plus(heavy): safe up to tile 200 on 8GB, tile 512 on 12GB
- Positive: No more OOM crashes from tile/model mismatch. Predictable performance per hardware class. Users can choose fast/balanced/quality without knowing tile sizes.
- Negative: Adds complexity to config resolution. Profile database must be maintained as new models/GPUs emerge.
Status: Accepted
Date: 2026-07-16
Even with conservative profiles, users may manually override --model or use legacy defaults that pair a heavy model with a large tile on insufficient VRAM.
Add CheckTileSafety() in hardware/profile.go that compares the active tile size against a VRAM/model lookup table. If the tile exceeds the safe limit, a warning is logged at pipeline startup. This does not block execution (user may know their hardware better than the heuristic).
- Positive: Early warning before a multi-hour pipeline crashes. Users see the warning and can reduce tile size.
- Negative: Heuristic-based — may false-positive on well-cooled overclocked cards or false-negative on cards with shared VRAM.