Convert and Compress: Format Conversion and Size Reduction

Yoink includes two complementary post-processing tools: Convert transforms a file into a different format, optionally trimming or cropping it along the way, while Compress reduces a video’s file size to a target in megabytes or a chosen quality level using ffmpeg. Both tools accept direct uploads for smaller files, and a chunked upload path for files up to 8 GB.

Convert
Compress

Format conversion

The converter remuxes or re-encodes a video or audio file into any supported container or audio format. It uses ffmpeg under the hood and intelligently decides whether to copy streams or re-encode based on codec compatibility and your preferences.

Simple upload (≤ typical browser limit)

POST /api/convert
Content-Type: multipart/form-data

Field	Default	Description
`file`	—	The media file to convert
`format`	`mp4`	Target format: `mp4`, `webm`, `mkv`, `mov`, `mp3`, `m4a`, `opus`, `wav`, `flac`
`quality`	`medium`	Re-encode quality: `high` (CRF 18), `medium` (CRF 23), `low` (CRF 28)
`reencode`	`auto`	`auto` — copy if codec is compatible; `always` — force re-encode; `never` — always stream-copy
`startTime`	—	Trim start — seconds or `HH:MM:SS`
`endTime`	—	Trim end — seconds or `HH:MM:SS`
`audioBitrate`	`192`	Audio bitrate for re-encodes: `64`, `96`, `128`, `192`, `256`, `320`
`cropRatio`	—	Preset aspect ratio crop: `16:9`, `9:16`, `1:1`, `4:3`, `4:5`
`clientId`	—	Per-client concurrency tracking

Large file path (chunked upload)

For files that exceed a typical form upload limit, use the three-step chunked upload flow before calling convert:

Initialise the upload

POST /api/upload/init
Content-Type: application/json

{
  "fileName": "source.mp4",
  "fileSize": 2147483648,
  "totalChunks": 42
}

Returns { "uploadId": "..." }. Maximum 200 chunks per upload.

Send each chunk

POST /api/upload/chunk/{uploadId}/{chunkIndex}
Content-Type: multipart/form-data

Send chunk data in the chunk field. Each chunk is up to 50 MB (ChunkSize).

Complete and convert

POST /api/upload/complete/{uploadId}

Returns { "filePath": "<token>", "fileName": "..." }. Use the filePath token in the convert-chunked request:

POST /api/convert-chunked
Content-Type: application/json

{
  "filePath": "<token>",
  "fileName": "source.mp4",
  "format": "webm",
  "quality": "high",
  "reencode": "auto",
  "startTime": "0",
  "endTime": "120",
  "audioBitrate": "192",
  "cropRatio": "16:9",
  "clientId": "your-client-id"
}

Returns { "jobId": "..." } — poll GET /api/job/{jobId}/status and download via GET /api/job/{jobId}/download.

Multi-segment extraction

The convert-chunked endpoint supports a segments array for extracting multiple non-contiguous clips and concatenating them into a single output file:

{
  "filePath": "<token>",
  "format": "mp4",
  "segments": [
    { "start": 10.0, "end": 45.5 },
    { "start": 120.0, "end": 180.0 }
  ]
}

Maximum 20 segments per job (MaxSegments).

Custom pixel-level crop

Instead of a preset aspect ratio, you can specify exact pixel coordinates:

{
  "filePath": "<token>",
  "format": "mp4",
  "cropX": 100,
  "cropY": 50,
  "cropW": 1280,
  "cropH": 720
}

Both cropW and cropH must be even numbers. The crop rectangle must fit within the source video bounds.

Re-encode modes explained

Mode	Behaviour
`auto`	Copies streams if the codec is compatible with the target container; re-encodes otherwise
`always`	Always re-encodes — use when you need guaranteed compatibility or want to apply CRF quality
`never`	Always stream-copies — fastest, but may fail if the codec is incompatible with the target container

Codec compatibility table

Container	Compatible codecs (copy)
`mp4`	h264, avc, hevc, h265
`webm`	vp8, vp9, av1
`mkv`	any codec
`mov`	h264, hevc, prores

Fetching a remote URL for conversion

If you have a URL rather than a local file, use POST /api/fetch-url to download it to the server first:

POST /api/fetch-url
Content-Type: application/json

{ "url": "https://example.com/video.mp4" }

Returns { "filePath": "<token>", "fileName": "...", "fileSize": ..., "duration": ..., "width": ..., "height": ... }. Use the filePath token with convert-chunked.

Video compression

The compressor uses ffmpeg’s libx264 encoder to shrink a video file. Choose between size mode (two-pass encoding to hit an exact MB target) or quality mode (single-pass CRF encoding for a consistent visual quality).

Simple upload (≤ typical browser limit)

POST /api/compress
Content-Type: multipart/form-data

Field	Default	Description
`file`	—	The video to compress
`mode`	`size`	`size` — hit a target file size; `quality` — use CRF
`targetSize`	`50`	Target size in MB (only used in `size` mode)
`quality`	`medium`	`high`, `medium`, or `low` (controls CRF in quality mode)
`preset`	`balanced`	Encoding speed preset (see table below)
`denoise`	`auto`	Noise-reduction filter strength
`downscale`	—	`true` to allow Yoink to downscale resolution to help hit the target size
`duration`	`0`	Video duration in seconds (used to calculate bitrate; probed automatically if `0`)
`progressId`	—	Correlate with SSE progress stream
`clientId`	—	Per-client concurrency tracking

Large file path (chunked upload)

Use the same three-step chunked upload flow described in the Convert tab, then call:

POST /api/compress-chunked
Content-Type: application/json

{
  "filePath": "<token>",
  "fileName": "video.mp4",
  "mode": "size",
  "targetSize": "25",
  "quality": "medium",
  "preset": "balanced",
  "denoise": "auto",
  "downscale": false,
  "clientId": "your-client-id"
}

Returns { "jobId": "..." } for async polling.

Preset reference

Preset	ffmpeg preset	CRF (high / medium / low)	Denoise default
`fast`	`ultrafast`	26 / 28 / 30	none
`balanced`	`medium`	22 / 24 / 26	auto
`quality`	`slow`	20 / 22 / 24	auto

Denoise filters

Level	Filter applied
`none`	No denoising
`light`	`hqdn3d=2:1.5:3:2.25`
`moderate`	`hqdn3d=4:3:6:4.5`
`heavy`	`hqdn3d=6:4:9:6`

When denoise is set to auto, the balanced and quality presets apply the filter automatically based on the source bitrate and resolution.

How size mode works

In size mode, Yoink runs a two-pass x264 encode:

Pass 1 — Analysis pass with fast-pskip=1, writes to a temporary log file.
Pass 2 — Encoding pass using the target bitrate calculated as:

video_bitrate_kbps = floor(((targetSizeMB × 1024 × 1024 × 0.95) − (96000 / 8 × duration)) × 8 / duration / 1000)

The bitrate budget reserves 96 kbps for the audio track when calculating the available video bitrate. The audio stream is encoded at 128 kbps AAC in the output. A 5 % safety margin (× 0.95) is applied to the target size to avoid exceeding it. Resolution may be automatically downscaled if downscale=true and the calculated bitrate would be insufficient for the source resolution.

The compressor always outputs an MP4 file with +faststart for streaming compatibility, regardless of the input container.

Use preset=fast for quick previews and preset=quality for final exports. The quality preset’s slow ffmpeg preset provides noticeably better results on low-bitrate targets.

Shared limits

Limit	Value
Max file size	8 GB
Max video duration	4 hours
Max concurrent jobs per client	3
Max segments (convert-chunked)	20
Max chunks per upload	200
Chunk size	50 MB

Get Started

Features

Self-Hosting

Convert and Compress: Format Conversion and Size Reduction

Format conversion

Simple upload (≤ typical browser limit)

Large file path (chunked upload)

Multi-segment extraction

Custom pixel-level crop

Re-encode modes explained

Codec compatibility table

Fetching a remote URL for conversion

Video compression

Simple upload (≤ typical browser limit)

Large file path (chunked upload)

Preset reference

Denoise filters

How size mode works

Shared limits

Build docs developers (and LLMs) love

Get Started

Features

Self-Hosting

Documentation Index

​Format conversion

​Simple upload (≤ typical browser limit)

​Large file path (chunked upload)

​Multi-segment extraction

​Custom pixel-level crop

​Re-encode modes explained

​Codec compatibility table

​Fetching a remote URL for conversion

​Video compression

​Simple upload (≤ typical browser limit)

​Large file path (chunked upload)

​Preset reference

​Denoise filters

​How size mode works

​Shared limits

Build docs developers (and LLMs) love

Format conversion

Simple upload (≤ typical browser limit)

Large file path (chunked upload)

Multi-segment extraction

Custom pixel-level crop

Re-encode modes explained

Codec compatibility table

Fetching a remote URL for conversion

Video compression

Simple upload (≤ typical browser limit)

Large file path (chunked upload)

Preset reference

Denoise filters

How size mode works

Shared limits