# FlowCompressor User Wiki FlowCompressor is a local macOS video workflow app for users who need to compress, prepare, merge, and recipe-edit video files without sending media to a cloud service. The app is organized around one visible question: what do you want to do with the selected clips? The primary browser-style entry point is [index.html](index.html), with the focused feature page at [How FlowCompressor Works](features/how-flowcompressor-works.html). This Markdown page is the reference layer for the same workflow. ```mermaid flowchart LR Files[Video files] --> Drop[Drop or import] Drop --> Tabs[Choose workspace] Tabs --> Batch[Batch Compress] Tabs --> Preview[App Store Preview] Tabs --> Merge[Video Merger] Tabs --> AI[AI Recipe] Mode[Processing Mode] --> Standard[Standard] Mode --> Hardware[Hardware] Mode --> Native[Apple Native] Standard --> Batch Standard --> Preview Standard --> Merge Standard --> AI Hardware --> Batch Hardware --> Preview Hardware --> Merge Hardware --> AI Native --> Batch Native --> Preview Native --> Merge Native --> AI Batch --> Outputs[Output files] Preview --> Outputs Merge --> Outputs AI --> Validate[Validate recipe] Validate -->|Supported| Outputs Validate -->|Not supported by selected mode| Guidance[Switch mode or edit recipe] Outputs --> Reveal[Reveal in Finder] ``` ## Main Workspaces | Workspace | Use It For | Typical Output | | --- | --- | --- | | `Batch Compress` | Compress many videos using the selected quality preset and processing mode. | One compressed video per input. | | `App Store Preview` | Create App Store Connect-ready preview videos with timing, sizing, and audio handling. | MP4 preview files. | | `Video Merger` | Combine clips in their selected order using hard cuts or crossfades. | One merged MP4. | | `AI Recipe` | Turn a plain-language instruction into a checked recipe for trims, joins, compression, exports, overlays, and compatible native edits. | One output or one output per selected input. | ## Importing Files FlowCompressor supports several import paths because users often start from different contexts: - Drag videos directly into the active workspace. - Use the workspace file picker to choose files or an output folder. - Drop or add more clips or audio files inside `AI Recipe`. - Ask AI Recipe to import prompt-referenced files, such as `Import elias_*.avi from the Desktop`. Imported AI files are listed under `AI Input Clips`. In AI Recipe, "selected" means the files currently shown in that list. The `Remove Files` control clears those imported files without clearing the prompt, so users can retry a recipe with a different set of inputs. ## Processing Modes | Mode | What It Means | Best Use | | --- | --- | --- | | `Standard` | The broadest compatibility path. | Mixed files, unusual codecs, subtitles, audio normalization, and complex edits. | | `Hardware` | Keeps broad recipe coverage while using Apple's accelerated encoder for compatible video output. | Large batches where speed matters but the workflow still needs Standard-level features. | | `Apple Native` | Uses Apple's AVFoundation/Core Image APIs inside the app, including GPU/Core Image rendering and hardware media engines where available. | Fast native compression, previews, hard-cut merges, and supported AI Recipe edits. | The processing mode is global. It affects Batch Compress, App Store Preview, Video Merger, and AI Recipe. When `Apple Native` cannot run a recipe, the app shows a compatibility warning before running and tells the user to switch to `Standard` or `Hardware`, or simplify the recipe. ## Performance And Coverage The modes are not just labels for speed. They also decide which operations are available. | Mode | Performance Profile | Coverage Profile | | --- | --- | --- | | `Standard` | Usually the most predictable baseline. It may be slower than accelerated paths, especially on large batches. | Broadest feature coverage and best fallback for unusual formats, subtitles, audio normalization, replacement audio, stabilization, and complex edits. | | `Hardware` | Faster than Standard for compatible video encoding because it uses Apple's accelerated encoder. | Keeps the broad Standard workflow while accelerating the final encode when possible. | | `Apple Native` | Often fastest for supported jobs because the app stays inside Apple's native media stack, uses GPU/Core Image rendering for visual operations, and can use hardware media engines for encoding. | Narrower than Standard/Hardware. It refuses unsupported recipes before running and shows what to change. | In practical terms: start with `Apple Native` when testing native performance on supported operations. Switch to `Hardware` when a recipe needs broader feature coverage but should still use acceleration. Use `Standard` when compatibility is more important than speed. ## Batch Compress Batch Compress is the fastest path when the goal is simply smaller files. 1. Choose a quality preset: `Small`, `Balanced`, or `High`. 2. Drop video files or use `Change` to choose an output folder. 3. Choose the processing mode from the header. 4. Click `Compress Batch`. 5. Use `Reveal` on finished rows to inspect the output. Rows show the selected processing mode and compression summary after export, so users can compare output sizes across modes. ## App Store Preview App Store Preview is for creating videos that match App Store Connect requirements. Key controls: - `Process`: first 30 seconds or speed up to fit 30 seconds. - `Target`: Mac, iPhone, or iPad preview sizes. Mac exports use `1920x1080`. - `Output`: explicit folder or source/default location. - `Processing Mode`: Standard, Hardware, or Apple Native. This workspace handles preview-specific sizing, 30 fps timing, and AAC stereo audio preparation. If a source has no audio, Flow Compressor adds a silent audio track so users do not need to manually combine several separate export steps. AI Recipe can also route App Store Preview prompts into this same preview-safe pipeline. Use AI Recipe when the user wants to describe the target in words, and use the App Store Preview tab when the user wants direct controls. ## Video Merger Video Merger combines selected clips into one timeline. - `Hard Cut`: joins clips directly in order. - `Crossfade`: blends between clips when using Standard or Hardware. - `Apple Native`: supports normalized hard-cut merges for compatible workflows. If clips have mixed size, rotation, or frame-rate, the native merge path can normalize them for hard-cut output. Crossfades require a broader processing mode. ## AI Recipe AI Recipe is a structured command console for video edits. Users type a plain instruction, the app generates a recipe, validates it, and then runs it only when the current inputs and processing mode support the requested work. ### Working With Multiple Movies When several movies are imported into AI Recipe, the prompt decides how the app uses them. There are three common patterns: | Prompt style | Result | Example | | --- | --- | --- | | Per-movie batch | One output file is created for each imported movie. | `Compress each selected video as balanced H.264 MP4.` | | Timeline join | One output file is created by playing movies one after another. | `Join all selected clips in the current order with hard cuts and export H.264 MP4.` | | Simultaneous layout | One output file is created with multiple movies visible at the same time. | `Put the two selected videos side by side and export H.264 MP4.` | Use `each selected video` when every movie should be processed separately. Use `join`, `merge`, or `current order` when clips should play sequentially. Use `side by side`, `split screen`, `vertical stack`, or `2x2 grid` when clips should play together in one shared frame. Side-by-side and grid layouts use `Standard` or `Hardware`. Multiple-movie prompt examples: - Separate outputs: `Compress each selected video as balanced H.264 MP4.` - Sequential hard cut: `Join all selected clips in the current order with hard cuts and export H.264 MP4.` - Sequential crossfade: `Join all selected clips with a 1 second crossfade and export H.264 MP4.` - Sequential named transition: `Join file 1 and file 2 with a 1-second circle_open transition between clips. Keep both clips at normal speed, preserve audio, and export H.264 MP4.` - Merge with per-clip speed: `Join file 1 and file 2 into one H.264 MP4. Add a 1-second visible wipe_left transition between the two clips. Keep file 1 at normal speed, then slow file 2 to 0.5x speed for its full duration. Preserve audio sync.` - Two-up split screen: `Put the two selected videos side by side, fit each video inside its half, use the shortest duration, mix audio, and export H.264 MP4.` - Vertical stack: `Stack the selected videos vertically in one 1080x1920 H.264 MP4, fit each clip, use the shortest duration, and mix audio.` - Four-up grid: `Create a 2x2 grid from all selected clips, crop each clip to fill its cell, mute audio, and export H.264 MP4.` - Three across: `Put three selected videos in one horizontal row, fit each video inside its cell, use the shortest duration, and export H.264 MP4.` Single-movie speed prompt examples: - Speed change with visible transition: `Edit this one video only. Keep source seconds 0-8 at 1x speed, slow source seconds 8-18 to 0.5x speed, then play source second 18 to the end at 1x speed. Add a short visible pixelize transition inside the same clip at the speed-change points around source seconds 8 and 18. Do not use a clip-to-clip crossfade or concatenate operation. Preserve audio sync and export one H.264 MP4.` - Speed up with wipe: `Keep source seconds 0-10 at 1x speed, then continue at 4x speed. Add a one-second wipe-left transition centered at the speed-change boundary at source second 10. Preserve audio sync and export H.264 MP4.` ### Replacing Audio AI Recipe can replace a video's audio with audio from another file in `AI Input Clips`. Add the main video first, then add either an audio file such as M4A, MP3, or WAV, or another video that contains the audio track to use. If `AI Input Clips` shows: | Number | File | | --- | --- | | `1` | `my_video.mp4` | | `2` | `music.m4a` | Use a prompt like: - `Replace the audio in file 1 with the audio from file 2 and export H.264 MP4.` - `Keep video from file 1, use audio from file 2, and export H.264 MP4.` Audio replacement uses `Standard` or `Hardware`. `Apple Native` does not support replacement audio yet and will ask the user to switch modes. ### App Store Preview Recipes When an AI Recipe prompt mentions `App Store Preview`, `App Preview`, or `App Store Connect` video, Flow Compressor treats it as a dedicated preview request instead of a generic recipe or custom advanced plan. This keeps the Recipe and Advanced buttons from producing different media plans for the same App Store Preview goal. Use one selected video for this workflow. The recipe uses the first 30 seconds, exports `1920x1080` for Mac, converts to constant `30 fps`, writes H.264 MP4, and prepares AAC stereo audio at `44.1 kHz`. If the source has audio, Flow Compressor keeps it. If the source has no audio, Flow Compressor adds a silent stereo track so the output still has an audio stream. Recommended test prompt: `Create an App Store Preview compatible MP4 from the selected video: export H.264 MP4, 1920x1080 for Mac, maximum 30 seconds, constant 30 fps, progressive video, AAC stereo audio at 44.1 kHz, keep source audio if present, otherwise add a silent stereo audio track.` App Store Preview recipes create output names ending in `_appstore_ai.mp4`. ### File Roles, Preview, And History `AI Input Clips` shows compact role chips beside each file. The first role comes from the file type, such as `Video`, `Audio`, `Image`, or `Subtitle`. After a recipe is generated, the app refines those roles with how the file is used, such as `Timeline`, `Audio source`, `Overlay`, or `Subtitle`. Generated recipes also show a compact explanation line before the technical details. For example, an audio replacement recipe may read: `1 output - H.264 MP4 - video from file 1 - audio from file 2 - Standard` Expand the explanation to review the inputs, output, and steps before running. Advanced media plans show the same kind of preview, focused on layout, labels, audio, and output settings. Use the history button beside `Examples` to reopen recent valid recipes and advanced plans. `Use Prompt` restores the original instruction. `Use Recipe` restores the generated recipe only when the current `AI Input Clips` list is compatible with the files the saved recipe expected. ### Templates, Safety Review, And Recovery Use `Templates` to start from reusable workflows such as compress, replace audio, join clips, side-by-side, 2x2 grid, thumbnail, and extract audio. Templates fill the prompt only; they do not run automatically. `Save Current` stores the current prompt as a local favorite so it can be reused later. When a generated recipe includes a step that can surprise the user, AI Recipe shows a compact `Review` row before running. Examples include replacing audio, muting audio, cropping, trimming, large layouts, or advanced plans with no audio map. Higher-risk items ask for confirmation when the user clicks `Run`. If a recipe is invalid, AI Recipe shows a recovery block instead of only listing raw validation errors. The block explains the problem, suggests a direct fix, and may show actions such as `Add Media`, `Use File Numbers`, `Hardware`, `Standard`, `Use Advanced`, `Regenerate`, or `Repair`. ### Grid Layouts Grid layouts place several imported movies into one shared video frame so they play at the same time. They are different from a merge: a merge plays clips one after another, while a grid shows clips together. Use `Standard` or `Hardware` for grids. Apple Native is not the recommended mode for side-by-side or multi-cell grid layouts. Key grid terms: | Term | Meaning | | --- | --- | | Grid shape | The row and column layout, such as `1x2`, `2x1`, `2x2`, or `1x3`. | | Canvas size | The size of the final output video, such as `1600x1440` or `3200x2880`. | | Cell size | The size of each grid slot. A `2x2` grid on a `1600x1440` canvas creates four `800x720` cells. | | Fit | Preserves the whole input frame. If the input shape does not match the cell shape, empty padding can appear. | | Fill / crop to fill | Fills the cell completely. This removes padding but may crop the edges of the video. | | Duration policy | `shortest duration` stops the grid when the shortest clip ends. | | Audio policy | `mute audio`, `mix audio`, or use the first clip's audio. | Canvas size matters. If the source movies are `1600x1440` and the app creates a default `1920x1080` grid, each `2x2` cell is `960x540`, which is a different shape. The app must shrink the `1600x1440` movie into that wide cell, causing large side padding. Instead, ask for a canvas that matches the source shape: - Downscaled `2x2`: `1600x1440` canvas, four `800x720` cells. - Full-size `2x2`: `3200x2880` canvas, four `1600x1440` cells. Good grid prompts: - `Create a 2x2 grid from all selected clips on a 1600x1440 canvas, fit each video inside its cell, use the shortest clip duration, mute audio, and export H.264 MP4.` - `Create a 2x2 grid from all selected clips on a 3200x2880 canvas, fit each video inside its cell, use the shortest clip duration, mute audio, and export H.264 MP4.` - `Put the two selected videos side by side on a 1600x720 canvas, fit each video inside its half, use the shortest duration, mix audio, and export H.264 MP4.` - `Stack the selected videos vertically on a 800x2160 canvas, fit each clip, use the shortest duration, and mute audio.` - `Create a 2x2 grid from all selected clips on a 1920x1080 canvas, crop each clip to fill its cell, use the shortest duration, and export H.264 MP4.` If black side bands appear, the canvas/cell shape probably does not match the source movies. Ask for an explicit canvas size. If white margins remain inside plot videos, those margins are part of the source frame; export the plots with tighter padding or use a crop/zoom step before the grid. Good Apple Native examples: - `Compress each selected video as balanced H.264 MP4.` - `Trim each selected video from 2 to 12 seconds, resize to 1080x1920, and export H.264 MP4.` - `Join all selected clips in the current order with hard cuts and export H.264 MP4.` - `Extract a thumbnail from the selected video at 4 seconds and save it as JPG.` Non-MP4 AI Recipe examples: - `Extract audio from the selected video and save it as M4A.` - `Create a GIF from the selected video from 2 to 6 seconds.` - `Extract a thumbnail from the selected video at 4 seconds and save it as JPG.` Batch Compress, App Store Preview, Video Merger, and ordinary AI video exports produce MP4-style video files. AI Recipe can also produce M4A, GIF, and JPG outputs when the requested task is extraction-oriented. Examples that should guide the user to Standard or Hardware: - `Put the selected videos side by side, fit each video, use the shortest duration, mix audio, and export H.264 MP4.` - `Create a 2x2 grid from all selected clips, crop each clip to fill its cell, mute audio, and export H.264 MP4.` - `Normalize audio loudness across all selected clips, stabilize the footage, and export H.264 MP4.` - `Add subtitles, replace the audio track, and stabilize the clip.` ## AI Recipe Test Examples Use these prompts to test the four main AI Recipe states: normal recipes, Advanced media plans, Ask answers, and recipes that should warn before running. ### Normal Recipe These prompts should create ordinary structured recipes that can be reviewed and run when the selected processing mode supports them. - `Compress each selected video as balanced H.264 MP4.` - `Trim each selected video from 0 to 5 seconds and export H.264 MP4.` - `Join all selected clips in the current order with hard cuts and export H.264 MP4.` - `Join file 1 and file 2 into one H.264 MP4. Add a 1-second visible wipe_left transition between the two clips. Keep file 1 at normal speed, then slow file 2 to 0.5x speed for its full duration. Preserve audio sync.` - `Edit this one video only. Keep source seconds 0-8 at 1x speed, slow source seconds 8-18 to 0.5x speed, then play source second 18 to the end at 1x speed. Add a short visible pixelize transition inside the same clip at the speed-change points around source seconds 8 and 18. Preserve audio sync and export one H.264 MP4.` - `Create a 2x2 grid from the four selected videos, fill every cell without side gaps, mute audio, and export H.264 MP4.` ### Advanced Use Advanced when the prompt needs precise layout details, labels, borders, or custom comparison grids. - `Create a 2x2 grid from the four selected videos, fill every cell without side gaps, add the file name as a black label at the top-left of each cell, draw a thin black border around every cell, mute audio, and export H.264 MP4.` - `Create a 4x1 horizontal comparison grid from the four selected videos, crop each cell to fill, add black file-name labels at the top-left, mute audio, and export H.264 MP4.` - `Create a 3x1 horizontal grid using the first three selected videos, fill each cell without side gaps, add black labels "case A", "case B", and "case C" at the top-left, mute audio, and export H.264 MP4.` ### Ask Use Ask when the user wants guidance instead of a runnable recipe. - `Why would a 2x2 grid still show white margins inside each video?` - `What is the difference between Recipe and Advanced mode?` - `Which mode should I use for a labeled comparison grid?` ### Should Warn Or Need Changes These prompts are useful for testing validation, missing assets, and selected processing mode limits. - `Normalize audio loudness, stabilize all clips, add subtitles, and export H.264 MP4.` - `Create a 2x2 grid with animated arrows and generated icons over each video.` - `Replace the original audio with a music track that I have not imported, then export H.264 MP4.` ## Prompt Compatibility Examples Use this table to understand which prompts are good Apple Native tests and which ones should use Standard or Hardware. | Prompt | Standard / Hardware | Apple Native | | --- | --- | --- | | `Compress each selected video as balanced H.264 MP4.` | Supported. | Supported; good native speed test. | | `Compress each selected video as high quality H.264 MP4.` | Supported. | Supported when the input codec is Apple-decodable. | | `Trim each selected video from 2 to 12 seconds and export H.264 MP4.` | Supported. | Supported for single-input or per-input recipes. | | `Resize each selected video to 1080x1920 and export H.264 MP4.` | Supported. | Supported for single-input or per-input recipes. | | `Crop the selected video to square, rotate 90 degrees, and export H.264 MP4.` | Supported. | Supported for single-input or per-input recipes. | | `Convert the selected video to 30 fps and export H.264 MP4.` | Supported. | Supported for single-input or per-input recipes. | | `Remove audio from each selected video and export H.264 MP4.` | Supported. | Supported for single-input or per-input recipes. | | `Fade in the video for 1 second and fade out for 1 second.` | Supported. | Supported for one input at a time. | | `Lower the audio volume to 50 percent and add a 1 second audio fade out.` | Supported. | Supported for one input at a time when audio exists. | | `Join all selected clips in the current order with hard cuts and export H.264 MP4.` | Supported. | Supported; Apple Native can use compatible or normalized hard-cut merge. | | `Join all selected clips with a 1 second crossfade and export H.264 MP4.` | Supported. | Supported only through the AI Recipe native path when the recipe includes a compatible timeline; the Video Merger Crossfade control should use Standard or Hardware. | | `Put the selected videos side by side, fit each video, use the shortest duration, mix audio, and export H.264 MP4.` | Supported; creates one simultaneous split-screen output. | Not supported; use Standard or Hardware. | | `Create a 2x2 grid from all selected clips, crop each clip to fill its cell, mute audio, and export H.264 MP4.` | Supported; creates one simultaneous grid output. | Not supported; use Standard or Hardware. | | `Add the text "Preview" at the bottom center of the selected video.` | Supported. | Supported for one input at a time. | | `Overlay the selected PNG logo in the top right of the selected video.` | Supported. | Supported for one input at a time when the image asset is available. | | `Denoise and sharpen the selected video and export H.264 MP4.` | Supported. | Supported for simple one-input filter recipes. | | `Extract a thumbnail from the selected video at 4 seconds and save it as JPG.` | Supported. | Supported. | | `Extract audio from the selected video and save it as M4A.` | Supported. | Supported when the input has audio. | | `Create a GIF from the selected video from 2 to 6 seconds.` | Supported. | Supported for one input at a time. | | `Normalize audio loudness across all selected clips and export H.264 MP4.` | Supported. | Not supported; use Standard or Hardware. | | `Replace the video audio with another selected audio track.` | Supported. | Not supported; use Standard or Hardware. | | `Add subtitles to the selected video and export H.264 MP4.` | Supported. | Not supported; use Standard or Hardware. | | `Stabilize the footage and export H.264 MP4.` | Supported. | Not supported; use Standard or Hardware. | | `Change speed: slow the first 5 seconds, then speed up the rest.` | Supported. | Not supported yet; use Standard or Hardware. | | `Apply subtitles, stabilize, normalize audio, and add a logo overlay.` | Supported. | Not supported because it combines unsupported and complex steps. | ## Safety And Feedback FlowCompressor keeps the user in the loop: - Files are selected explicitly by drag/drop, prompt import, or folder access. - The app previews generated AI recipes before running them. - Unsupported Apple Native recipes show a visible warning and disable `Run`. - Active jobs can be stopped. - Finished outputs can be revealed in Finder. - Processing is local to the Mac. ## Troubleshooting | Symptom | What To Do | | --- | --- | | Apple Native refuses a recipe | Read the warning, then switch Processing Mode to `Standard` or `Hardware`, or remove unsupported steps. | | An imported file fails in Apple Native | The file may use a codec Apple cannot decode. Use `Standard` or `Hardware`. | | Merge output does not match expectations | Confirm clip order, strategy, and whether mixed geometry needs normalization. | | AI Recipe generated the wrong operation | Edit the prompt and click `Generate` again before running. | ## Documentation Status This page describes the user-facing behavior of FlowCompressor. The app source remains the final authority for exact codec behavior, compatibility checks, and export implementation details.