GlitchCraft

GlitchCraft is a local Flask prototype for reproducible glitch, noise, pixel, scan, distortion, and signal treatments for images and video.

The current interface is a dependency-free Flask workspace. Images upload once, keep their original visible, update a deterministic processed preview as controls change, and create a downloadable PNG only when explicitly exported. Image and video sources and explicit outputs have persistent local identity. Video processing uses a bounded, cancellable queue whose job state survives application restarts.

Requirements

• Python 3.11 or newer
• FFmpeg and FFprobe on PATH for video inspection and browser-safe output

FFmpeg is not required for effect-engine unit tests.

Setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt

On macOS or Linux, activate with source .venv/bin/activate.

Run

python app.py

Open http://127.0.0.1:5000. The default port and existing routes are preserved. The managed media library defaults to data/ and is ignored by Git. Configure DATA_ROOT to move it to another local user-data location. The service has no authentication and is intended only for loopback use; do not expose it directly to the public internet.

Image workflow

• Upload PNG, JPEG, BMP, or TIFF content up to 40 million pixels.
• Compare the original and processed image inline.
• Adjust controls to request a debounced preview without re-uploading.
• Reuse the same recipe and seed for preview and full-resolution export.
• Choose Export PNG, then explicitly download the managed result.

Automatic previews return temporary PNG bytes and do not create output files. Sources and explicit exports use opaque persistent identity and survive restarts when the same data root is reused. They remain until explicitly deleted; they are not deleted automatically by age.

Machine-readable local discovery is available at /app-manifest.json, /metadata, /health, /ready, /api/capabilities, and /api/storage.

Validate

python check.py
git diff --check
npm run test:browser

The validation command runs formatting, lint, strict type checking, tests, statement and branch coverage, and repository consistency checks.

Architecture

• Architecture
• Effect engine
• Image workflow and API
• Video workflow and API
• Video job lifecycle
• Persistent storage
• Recovery
• Craft service contract
• Testing
• Product direction

The internal recipe contract supports a schema version, root seed, ordered effect instances, stable IDs, enabled states, and strict effect-specific parameters. User-facing recipe import/export and seed controls are intentionally deferred.

Video uploads are inspected once with FFprobe, timestamp previews reuse the persisted source, and full jobs produce H.264/yuv420p MP4 output. Source audio is preserved as AAC at 192 kbps by default or can be removed. Streaming supports HEAD and one closed, open-ended, or suffix byte range. Legacy filename-oriented routes remain temporarily available for compatibility, but the current UI does not use them. True geometric distortion/datamoshing is not implemented.

License

GlitchCraft is available under the terms in LICENSE.md.