Filetwist

Self-hosted image, audio, and video conversion for a household. Upload files through the web interface, choose a named operation, and download individual results or a ZIP. A local CLI provides the same conversion profiles.

Filetwist uses Go 1.27, embedded HTMX, FFmpeg/ffprobe, and libvips. Conversion outputs are checked against the selected profile before they become available. These checks cover declared, probe-visible properties, not every visual defect or opaque metadata payload. Keep your originals.

One shared workspace, not private user accounts. Anyone who can access the service can access and manage its jobs. There is no built-in authentication, TLS, or multi-tenancy. Use a trusted network or an authenticated reverse proxy.

Quick start with the published image

You need Docker with Compose. The public container package includes Filetwist, FFmpeg and libvips. No registry login or compilation is needed. Download and extract the v0.0.2 source ZIP to obtain its matching Compose files, then open a terminal in that directory. Start the released image, pinned to its immutable digest:

FILETWIST_IMAGE=ghcr.io/guigui42/filetwist@sha256:1313a23528b3c66d5e5167365f1b0aa7be4f70c78a1e8f1a935e178dc75a17fa \
FILETWIST_PORT=127.0.0.1:8080 \
docker compose \
  -f deploy/compose.yaml \
  -f deploy/compose.cpu.yaml \
  up --no-build --pull always --detach --wait

Open http://127.0.0.1:8080/. Upload files, review the detected media and selected operations, then convert. Jobs expire after 24 hours by default, and you can cancel or delete them.

To stop the service while keeping its data volume:

docker compose -f deploy/compose.yaml -f deploy/compose.cpu.yaml down

The supported container target is Linux/amd64. On macOS, use the CPU mode above; Apple Silicon runs this image under Docker emulation. There is no supported arm64 image or native macOS acceleration. Linux hosts with a suitable Intel render device can use the VA-API override.

Quick start from source

For development, clone the current repository and run the following from its root. This builds only the Go application over the immutable media-runtime image pinned in deploy/Dockerfile. It pulls that seed on the first build; FFmpeg and libvips are not recompiled:

FILETWIST_IMAGE=filetwist:local FILETWIST_PORT=127.0.0.1:8080 \
docker compose \
  -f deploy/compose.yaml \
  -f deploy/compose.cpu.yaml \
  up --build --pull never --detach --wait

Release artifacts

Version tags automate Linux/amd64 binary releases and, after redistribution approval, GHCR images. See the v0.0.2 release for archives, checksums and corresponding source, and the public package for image tags and digests. The binary archive contains both executables but requires converter tools installed separately; see binary installation. For images, see pull-based deployment. Maintainer setup and publishing gates are in the release guide.

Operations

Operation	Output
compatible_photo	JPEG, orientation applied, transparency flattened onto white
email_photo	JPEG fitted within a 1920-pixel longest edge, quality 85
smaller_photo	WebP, quality 80
lossless_image	PNG with supported transparency preserved
compatible_video	H.264 MP4 with AAC when usable audio is present
smaller_video	H.264 MP4 fitted within 1280 x 720
extract_audio	AAC in M4A
compatible_audio	Stereo 48 kHz MP3
lossless_audio	FLAC

These are conversion profiles, not archival copies. They can re-encode, strip metadata, drop tracks, downmix audio, or tone-map supported HDR video to SDR. Smaller modes and email_photo do not guarantee a smaller file. The email profile never upscales and flattens transparency onto white. Animated/multipage images and HDR still-image tone mapping are unsupported. See behavior and limitations before converting important files.

Documentation

• Deployment and configuration
• CLI usage and exit codes
• Web workflow, conversion behavior, and limitations
• Reverse proxy, TLS, and authentication
• Contributing and release checks
• Security policy and private reports
• Third-party notices and redistribution

License

Filetwist is licensed under Apache-2.0. Generated fixtures carry their license information in the fixture manifest. Vendored HTMX retains its upstream license. Container dependencies have their own licences; see third-party notices.