Video-Processing-Scripts/Create-PillarBox.md

Create-PillarBox.ps1

Creates a pillar-boxed (16:9) video file from a source video using ffmpeg, with selectable side-bar effects ranging from solid colors to blurred backgrounds derived from the video itself.

The video above was generated using the Compare-Videos.ps1 script.

Each video shows the same source material with a different effect as follows:

Left side	Right side
black	standard
gaussian	dark

Synopsis

Wraps the source video in a 16:9 frame so it can be played on standard widescreen displays without stretching:

• Portrait-like sources (e.g. 9:16, 1:1) get vertical bars on the left and right (true pillar-boxing).
• Sources wider than 16:9 get horizontal bars on the top and bottom (letter-boxing).
• Square (1:1) sources with -Vertical are wrapped in a 9:16 portrait frame instead, with horizontal bars on the top and bottom — for vertical platforms such as Shorts, Reels, or TikTok.
• The source video is scaled to fit the chosen output frame while preserving its aspect ratio, then centered.
• The bars themselves can be solid black/white or filled with a stylised, blurred copy of the video.

Parameters

• -Video (required): Path to input video file (.mp4 extension added if missing)
• -Target (optional): Path to output video file (.mp4 extension added if missing). If omitted, defaults to the source filename with the -Effect value (lowercased) appended after a dash and saved alongside the source — e.g. video.mp4 + -Effect Black produces video-black.mp4 next to the source. When -Vertical is used, -vertical is appended after the effect, just before the extension — e.g. video-black-vertical.mp4.
• -Effect (required): Visual treatment of the side bars. One of black, white, silver, gray, charcoal, standard, dark, gaussian, or color:RRGGBB for an arbitrary hex color (case-insensitive on both the keyword and the hex value). See Effects for a detailed description.
• -Vertical: Only valid when the source video is square (1:1). Produces a 9:16 portrait output with the bars on the top and bottom instead of the default 16:9 landscape output with bars on the sides. All other parameters (-Effect, -Size, -FPS, -Audio, -NoAudio, -CRF) behave identically, just applied to a portrait frame. When -Target is omitted, the auto-generated filename ends with -vertical (e.g. video-black-vertical.mp4). Using it with a non-square source throws an error.
• -Size (optional): Output video size. Possible values: 480p, 720p, 1080p, HD, 1440p, 2K, 2160p, 4K, or custom width:height. If not specified, the smallest standard 16:9 size that fully contains the source is chosen automatically. With -Vertical, named presets are transposed to portrait (1080p → 1080x1920, 4K → 2160x3840); a custom width:height is always used exactly as given.
• -FPS (optional): Frames per second for the output video. Uses the input video's FPS if not specified.
• -NoAudio: Exclude audio from the output video. Cannot be combined with -Audio.
• -Audio (optional): Path to an alternate audio file to use for the target video. When specified, this audio replaces the source video's audio (re-encoded as AAC 192k, trimmed to the shortest stream).
• -CRF (optional): Constant Rate Factor for video encoding (0-51, lower is better quality). When specified, overrides both the source video bitrate and the default -crf 8 fallback.

Effects

The -Effect parameter controls what fills the area around the source video inside the 16:9 frame. The eight effects fall into two groups:

Solid colors

These produce flat, uniform bars. They are the cheapest to encode and are best when you want the viewer's eye to ignore the bars completely.

• black — Solid black bars (#000000). Standard television "matted" look. Maximum contrast against the picture; effectively invisible on OLED/dark-room playback.
• white — Solid white bars (#FFFFFF). High-key look suitable for product/light backgrounds, slideshows, and graphic-design contexts.
• silver — Solid silver bars (#C0C0C0). Light neutral gray; softer than white while staying bright. Useful when pure white feels too aggressive against the picture.
• gray — Solid mid gray bars (#808080). 50% luminance neutral; sits between dark and bright content without leaning either way. A safe default for mixed/unknown content brightness.
• charcoal — Solid charcoal bars (#36454F). Very dark, slightly blue-tinted gray. Almost as unobtrusive as black on OLED but with a more refined look in lit rooms or on LCD screens where pure black can look gray anyway.
• color:RRGGBB — Solid bars in any hex color you specify. The six hex digits are case-insensitive, so color:FFFF00, color:ffff00, and color:FfFf00 all produce the same bright yellow bars. Examples: color:FFFF00 (yellow), color:1E90FF (dodger blue), color:8B0000 (dark red). Use this when none of the named presets match your branding or scene palette.

Blurred-background ("ambient") effects

These three effects all use the same fundamental technique: the source video is duplicated; one copy is scaled to fill the 16:9 frame (so the picture overflows the visible area in one dimension and is cropped) and then blurred to become the background. The original, un-blurred picture is then centered on top at its true aspect ratio. The result is that the bars are not empty space — they are a soft, motion-synchronised continuation of the video, similar to the "ambient backlight" treatment used on Apple TV and YouTube.

The three effects differ only in how the background is treated before the original picture is laid on top:

• standard — Soft, neutral, slightly zoomed.

  • Scaling: the background copy is scaled to roughly 110% of the output frame and then cropped, giving the bars a subtle "pushed beyond the edges" feel rather than a flat fit. This avoids hard edges where the cropped border would otherwise sit exactly at the frame edge, and adds a barely-noticeable parallax depth.
  • Blur: a fast box blur of moderate radius. Box blur is computationally cheap; visually the background becomes recognisable smears of color and motion, but with slight box-shaped artefacts on sharp edges if you look closely.
  • Brightness/color: unchanged. The bars therefore retain the source's full brightness and saturation.
  • What you'll see: side bars filled with soft, recognisable shapes from the picture — sky color, skin tones, scenery — that move and shift in sync with the video. The center picture pops because it is sharp against a softer surround, but the overall image stays bright.
  • Best for: most general-purpose playback. Music videos, vlogs, product demos.

• dark — Same blur as standard, but dimmed.

  • Scaling: background fills the frame exactly (no extra zoom).
  • Blur: same box blur as standard.
  • Brightness/color: brightness is reduced (~ -25%) and saturation is reduced to ~80%, producing a darker, more muted background. The center video is not affected — only the bars.
  • What you'll see: side bars in the same shapes and motion as standard, but visibly darker and less colorful, so the eye is drawn more strongly to the original picture in the middle. Good for cinematic or moody content where the bars should "sink into" the screen.
  • Best for: film clips, dramatic content, dark-room viewing, or any time standard feels too bright/distracting.

• gaussian — Smooth, premium-looking blur.

  • Scaling: background fills the frame exactly (no extra zoom).
  • Blur: a Gaussian blur with a large sigma (~30). Gaussian blur is much more computationally expensive than box blur, but it produces a smoother fall-off with no visible artefacts at any zoom level. Sharp features in the original picture become unrecognisable color clouds.
  • Brightness/color: unchanged.
  • What you'll see: side bars that look like a smooth, abstract color wash that clearly comes from the video but where you can no longer make out shapes — only ambient color. Closest to the "broadcast TV" pillar-box look used by streaming services.
  • Best for: professional/broadcast deliverables, finished cuts where rendering time is acceptable, and any content where the standard blur looks too "blocky".

Quick comparison

Effect	Background source	Blur type	Brightness	Use when…
black	none (solid #000000)	—	—	You want the bars to disappear visually.
white	none (solid #FFFFFF)	—	—	You want a bright, graphic-design feel.
silver	none (solid #C0C0C0)	—	—	You want a light bar that's softer than pure white.
gray	none (solid #808080)	—	—	Neutral 50% gray that doesn't lean light or dark.
charcoal	none (solid #36454F)	—	—	A refined near-black that holds up on LCD/lit rooms.
color:RRGGBB	none (solid custom hex, case-insensitive)	—	—	You need an arbitrary brand or accent color, e.g. color:FFFF00.
standard	video, ~110% zoom	box blur (fast)	normal	General use; you want context in the bars.
dark	video	box blur (fast)	dimmed & desaturated	Cinematic look; you want focus on the picture.
gaussian	video	Gaussian (slow, smooth)	normal	Premium/broadcast look; rendering time is OK.

Size selection

When -Size is omitted, the script picks the smallest standard 16:9 preset that holds the source's bounding box — i.e. the preset's long side must be at least the source's long side and its short side at least the source's short side:

• A 1080×1920 portrait source → 1920x1080 (1080p) — vertical bars on either side.
• A 720×1280 portrait source → 1280x720 (720p) — vertical bars on either side.
• A 1080×1080 square source → 1920x1080 (1080p) — vertical bars on either side, source kept at its native 1080×1080.
• A 512×512 square source → 1280x720 (720p) — the 480p frame (854×480) is too short to hold 512 px.
• A 2560×1080 ultra-wide source → 2560x1440 (1440p) — horizontal bars top and bottom.
• A source too large for any preset → an even-rounded custom 16:9 frame that holds the source's bounding box (e.g. 4000×4000 → 7112x4002).

Checking both sides matters most for square-ish sources: a 1080×1080 source would fit inside a 1280×720 frame only by being shrunk to 720×720, so the next preset up is used instead and no resolution is lost.

You can always force a specific size with -Size 1080p, -Size 4K, or a custom -Size 1920:1080.

With -Vertical (square sources)

The same logic applies to a transposed 9:16 frame:

• A 1080×1080 square source → 1080x1920 (1080p transposed) — horizontal bars top and bottom, source kept at 1080×1080.
• A 512×512 square source → 720x1280 (720p transposed) — horizontal bars top and bottom.
• -Size 1080p → 1080x1920, -Size 720p → 720x1280, -Size 4K → 2160x3840.
• A custom -Size 1080:1920 is used verbatim (no transposition).

Examples

Auto-named output (no -Target specified):

.\Create-PillarBox.ps1 -Video video.mp4 -Effect black
# Produces video-black.mp4 next to video.mp4

.\Create-PillarBox.ps1 -Video vlog.mp4 -Effect Gaussian
# Produces vlog-gaussian.mp4 (effect name is always lowercased)

Pillar-box a portrait video with black bars at 1080p:

.\Create-PillarBox.ps1 -Video portrait.mp4 -Target portrait_16x9.mp4 -Effect black -Size 1080p

Turn a square video into a 9:16 vertical video (bars on top and bottom):

.\Create-PillarBox.ps1 -Video square.mp4 -Effect black -Vertical -Size 1080p
# Produces square-black-vertical.mp4 at 1080x1920 with black bars above and below the picture

.\Create-PillarBox.ps1 -Video square.mp4 -Target reel.mp4 -Effect gaussian -Vertical
# Blurred ambient bars on top and bottom; size derived from the source (1080x1080 -> 1080x1920)

Auto-size, white bars:

.\Create-PillarBox.ps1 -Video clip.mp4 -Target clip_white.mp4 -Effect white
# Output size derived from source dimensions

Custom yellow brand color (auto-named output):

.\Create-PillarBox.ps1 -Video clip.mp4 -Effect color:FFFF00
# Produces clip-color-ffff00.mp4 with solid yellow side bars.
# The hex value is case-insensitive: -Effect color:ffff00 works identically.

Soft ambient blur background (general purpose):

.\Create-PillarBox.ps1 -Video vlog.mp4 -Target vlog_16x9.mp4 -Effect standard -Size 1080p

Cinematic darkened blur:

.\Create-PillarBox.ps1 -Video scene.mp4 -Target scene_16x9.mp4 -Effect dark -Size 1080p

Broadcast-quality Gaussian blur:

.\Create-PillarBox.ps1 -Video music_video.mp4 -Target broadcast.mp4 -Effect gaussian -Size 1080p

Force 4K output:

.\Create-PillarBox.ps1 -Video clip.mp4 -Target clip_4k.mp4 -Effect gaussian -Size 4K

Custom resolution:

.\Create-PillarBox.ps1 -Video clip.mp4 -Target clip.mp4 -Effect black -Size 1920:1080

Replace audio with a soundtrack:

.\Create-PillarBox.ps1 -Video video.mp4 -Target output.mp4 -Effect standard -Audio soundtrack.mp3
# Source audio is dropped; soundtrack.mp3 replaces it (AAC 192k, trimmed to shortest stream)

Strip audio entirely:

.\Create-PillarBox.ps1 -Video video.mp4 -Target silent.mp4 -Effect black -NoAudio

Force a specific FPS:

.\Create-PillarBox.ps1 -Video video.mp4 -Target output.mp4 -Effect standard -FPS 30

Override quality with CRF:

.\Create-PillarBox.ps1 -Video video.mp4 -Target output.mp4 -Effect gaussian -CRF 18
# CRF 18 instead of default CRF 8 / source bitrate

Safe Execution

This script supports -WhatIf and -Confirm for safe execution:

• -WhatIf: Simulate the operation without creating files. Prints the full ffmpeg command that would have been run.
• -Confirm: Prompt for confirmation before each state-changing operation.

Simulate without making changes:

.\Create-PillarBox.ps1 -Video video.mp4 -Target output.mp4 -Effect standard -WhatIf

Prompt before creating files:

.\Create-PillarBox.ps1 -Video video.mp4 -Target output.mp4 -Effect gaussian -Confirm

Quality Preservation

• Codec: output is encoded with libx264 (H.264) using yuv420p and the slow preset.
• Bitrate: priority is -CRF (when specified) → source video bitrate (via -b:v) → fallback -crf 8 (near-lossless).
• Audio: when present and not replaced/excluded, audio is stream-copied with no quality loss. When -Audio is used, the replacement audio is re-encoded to AAC 192k.
• Aspect ratio: source content is never stretched — only scaled proportionally and padded.

Notes

• Requires ffmpeg and ffprobe on the Windows PATH.
• Output dimensions are forced to even pixels for yuv420p compatibility.
• The gaussian effect is noticeably slower to encode than standard/dark; expect a real-time-or-slower rendering speed at 1080p on typical CPUs.
• The standard and dark effects use box blur for speed; if you see visible block-like edges in the bars, switch to gaussian for a smoother result.
• When the source aspect ratio is already 16:9, all five effects produce a visually identical output (the source fills the frame; the bars have zero size).
• -Vertical is rejected for non-square sources: a 16:9 or 9:16 source already has an unambiguous bar orientation, so the switch would only be a source of confusion.