File2VideoConverter

File2VideoConverter is a native macOS SwiftUI app that stores arbitrary files inside a visual video format and restores the original file from that video later.

The project uses the custom FTV1 transport format: file bytes are wrapped in a ZIP-compatible payload, split into validated data blocks, mapped to black-and-white visual cells, written as video frames through AVFoundation, and decoded back into the original file.

Status

This project is functional but still experimental. It is intended for local testing, format iteration, and reliability experiments with different codecs, resolutions, cell sizes, and error-correction settings.

The default path uses ProRes 422 in a MOV container. Lossy codecs such as H.264 and HEVC are available, but they require careful bitrate calibration because small video artifacts can become byte errors during decoding.

Features

• Encode arbitrary files into real video files using AVFoundation
• Decode FTV1-generated videos back into the original file
• Preserve the original filename and timestamps through a ZIP-compatible payload
• Optional zlib compression around the ZIP payload
• Optional Reed-Solomon parity per data block
• Optional sync border for more robust sampling and auto-detection
• Configurable resolution, cell size, frame rate, chunk size, codec, and bitrate preset
• Built-in bitrate calibration for lossy codecs
• Detailed status and log output for CRC32, ZIP payload handling, container blocks, video frames, and finalization
• Native macOS file and folder pickers
• Content-sized SwiftUI window that adapts to visible controls and status output

Requirements

• macOS with AVFoundation support
• Xcode
• SwiftUI and AppKit

The app is a standard Xcode project. Open File2VideoConverter.xcodeproj in Xcode and build/run the File2VideoConverter scheme.

Basic Workflow

1. Open the app.
2. Choose Encode or Decode.
3. Select the input file or FTV1 video.
4. Select an output folder.
5. For encoding, adjust settings such as compression, error correction, cell size, resolution, codec, bitrate, and chunk size.
6. Start the job.
7. Watch the detailed status and log output.
8. Use the Finder button to reveal the generated video or restored file.

Encoding Pipeline

Encoding currently runs through these stages:

1. Read file attributes and calculate a streaming CRC32.
2. Build a ZIP-compatible single-file payload.
3. Optionally compress the full ZIP payload with zlib.
4. Plan the FTV1 container header, data blocks, Reed-Solomon parity, and frame distribution.
5. Create each data block with payload length, payload bytes, block CRC32, and optional parity.
6. Serialize container bytes into frame payloads.
7. Add frame headers and frame CRCs.
8. Render frame bytes into black-and-white cells.
9. Stream frames into a video file through AVFoundation.

Decoding Pipeline

Decoding reverses the process:

1. Open the video with AVFoundation.
2. Read cell size from metadata or detect settings from the first frame.
3. Detect sync border usage.
4. Sample data cells with majority voting.
5. Rebuild frame payload bytes.
6. Parse and validate the FTV1 container header.
7. Parse data blocks, verify CRC32, and use Reed-Solomon correction when needed.
8. Optionally decompress zlib data.
9. Extract the ZIP payload and write the restored file.

If a file with the same name already exists in the output folder, the decoder writes a unique decoded filename instead of overwriting it.

FTV1 Format Summary

FTV1 uses deterministic little-endian binary serialization.

The container header stores:

• magic value FTV1
• version 0x0101
• original file size
• payload size
• block size and block count
• frame width and height
• cell size and bits per cell
• Reed-Solomon parity configuration
• compression method
• video profile
• header CRC32

Each data block stores:

• block index
• payload length
• payload bytes
• CRC32 over the payload
• optional Reed-Solomon parity bytes

Each visual frame stores:

• frame magic 0xAA55
• frame type
• frame index and total frame count
• payload bit count
• CRC32 over frame header fields and payload
• frame payload bytes

Bits are written MSB-first. One visual cell currently stores one bit: black is 0, white is 1.

Codec Guidance

For reliable local round trips, use ProRes first:

• ProRes 422 is the default recommendation.
• ProRes 422 HQ and ProRes 4444 are also reliable but create larger files.
• H.264 and HEVC can work with sufficient bitrate, larger cells, and calibration.

For platform round trips such as upload/download workflows, use larger cells, enable sync border, and enable strong Reed-Solomon correction. See COMPATIBILITY.md for the current compatibility notes.

Progress Logging

The UI logs every pipeline progress message. The current implementation intentionally exposes detailed internal work, including:

• CRC32
• ZIP-Payload
• zlib-Kompression
• Container schreiben
• Video schreiben
• Video lesen
• Container dekodieren
• zlib-Dekompression
• ZIP-Extraktion

Container logging is especially verbose. For each data block it can show payload slicing, block CRC32, Reed-Solomon parity or correction, serialization, frame-buffer handoff, and ZIP-payload assembly.

Project Structure

File2VideoConverter/
  File2VideoConverter/
    Core/        Pipeline coordination, calibration, row workers, settings detection
    FileSystem/  ZIP-compatible payload creation and extraction
    Format/      Binary I/O, FTV1 headers, blocks, CRC32, compression, Reed-Solomon
    Media/       AVFoundation video reading and writing
    Render/      Visual frame byte/cell conversion
    Prototype/   Earlier Python experiments

Important reference files:

• PROJECT_CONTEXT.md contains the current development context.
• PROJECT_DOCUMENTATION.md contains a more detailed technical overview.
• COMPATIBILITY.md tracks codec, resolution, and cell-size reliability notes.
• File2VideoConverter/ftv1_spec_v1_1.md documents the current FTV1 format.

Current Limitations

• The ZIP payload currently supports a single file.
• ZIP-internal deflate is not implemented; optional zlib compression wraps the full ZIP payload instead.
• zlib progress is only reported at start and finish because Foundation's compression API does not expose intermediate progress.
• Video reliability depends on codec, bitrate, scaling, platform processing, and chosen cell size.
• Very detailed per-block logging can produce many log entries for large files.
• Broad automated round-trip coverage is still missing.

Development Notes

The core pipeline types are marked nonisolated where needed so CPU-heavy work does not accidentally run on the SwiftUI main actor. Pixel sampling and rendering use bounded multi-core row processing through ParallelRowWorker, with an optional maximum CPU mode for more aggressive throughput.

The project is still evolving. When changing format behavior, keep PROJECT_CONTEXT.md, PROJECT_DOCUMENTATION.md, and ftv1_spec_v1_1.md in sync.