Yautja

Yautja is a skill for Claude and Codex, powered by a local Python tool for sci-fi image and video effects: synthetic thermal colors, subject outlines, animated targeting, alien glyphs, and an audio-reactive HUD.

For entertainment purposes only. Colors assigned during re-skinning are purely algorithmically generated, with some randomness. They do not represent measured temperatures. HUD elements are for entertainment/costume/cosplay purposes only.

Use the CLI directly, or let Claude or Codex operate it. Videos use FFmpeg. yautja.ai.

Fremont	Murphy
Netrunner	Focus

The large hero uses --stylepreset yautja: Cinematic detail, 12 soft thermal levels, red HUD, cyan annotations, and CRT lines. The smaller previews show four alternative styles. The waveform follows the source audio. View a still frame.

Previews are 480×270; click one to open its 960×540 version on GitHub. The hero is also 960×540. The four preset previews below the hero play at normal source speed, 24 fps for four seconds. Comparison recipes and preview details.

Start here: Install and convert · Choose a look · Customize · Save a style · Export controls · Troubleshooting · Agent skill · Every option

Quick start

Install the skill for Claude or Codex:

npx skills add petehottelet/yautja

Then ask: “Use Yautja to convert this photo with the Ripley preset.” The skill checks the local runtime and guides setup for the look you choose. Agent and global installation options.

Direct CLI use

Install Yautja from PyPI. Requires Python 3.10+. Use an activated virtual environment; Windows and macOS/Linux setup shows how to create one.

Base installation. The base package converts images and video with a lightweight thermal filter. Try it on a JPEG or PNG; images need no FFmpeg or model downloads. For subject segmentation and the gallery presets, follow the setup below.

pip install yautja
yautja --version
yautja --doctor --media image
yautja "photo.jpg" "photo-yautja.png"

Segmented looks

For the gallery's Low Detail, Cinematic, Detailed, and Very Detailed looks, install the semantic extra and explicitly download the models once. You can install this extra directly without installing the base command first. Use the same environment's Python throughout:

python -m pip install "yautja[semantic]"
python -m yautja --download-models
python -m yautja --doctor --media image --thermal cinematic
python -m yautja "photo.jpg" "photo-cinematic.png" --thermal cinematic --verbose

The pinned models use roughly 1.2 GB and are reused from the local cache; ordinary conversions do not download them. Palettes work with the base filter. Palette starter presets and Yautja select Cinematic; Netrunner, Focus, Relic, Murphy, and Fremont use segmented outlines and need the same setup. Thermal presets can also use --thermal luminance; subject outlines, code, titles, and analysis require a segmented mode. Segmentation and GPU setup.

Video

Install FFmpeg and ffprobe separately and put them on PATH. With the base package, convert a video:

yautja --doctor
yautja "input.mov" "output-yautja.mp4"

After segmented setup, try a five-second Cinematic preview:

python -m yautja --doctor --thermal cinematic
python -m yautja "clip.mov" "clip-preview.mp4" --thermal cinematic --verbose --timecode --duration 5

Remove --duration 5 and choose a new output filename for the full video. Sound is retained unless --mute is used; --timecode adds elapsed time beneath the alien readout. Silent videos use a generated waveform. Existing files require explicit --overwrite.

Other installation options: pipx install yautja (or pipx install "yautja[semantic]") provides an isolated CLI. Existing compatible pipx installations can be reused. Source checkouts and offline release wheels are covered in the runtime guide. For upgrades, use the environment you installed into.

JPEG and PNG inputs save directly to PNG, retaining aspect ratio and applying EXIF orientation. Stills freeze animated HUD features in a settled state. Videos export H.264/AAC MP4; the source remains untouched.

To reproduce the hero after segmented setup:

yautja "clip.mov" "hero.mp4" --stylepreset yautja --verbose --timecode --duration 4

Choose a look

Choose a complete preset for a coordinated scene and HUD; a palette starter for Cinematic with named colors; --palette to change only colors; or --thermal to choose the image treatment independently. Without a preset, the command uses --thermal luminance with Yautja colors. --stylepreset yautja adds the complete Cinematic recipe.

Complete preset	Scene	HUD and targeting
yautja	Soft thermal bands and dark scenery	Red HUD, cyan callouts, CRT lines
fremont	Detailed red/burgundy source	Bold white analysis, persistent translucent scan disk
murphy	Source detail with a slight blue cast	Glowing green box and thinking caption
focus	Dark, cool source detail	Neon-purple HUD, blue grid and waveform, thin holographic edges, one gliding hexagon
relic	Focus scene grade	Hot-pink triangles and rising light streams behind each body core
netrunner	Dark green source tint	Red edges, upward Cyber code, cyan titles, yellow carets
ripley	Near-black, burnt-orange and amber thermal colors	Orange glyphs and callouts, brighter amber waveform

All complete presets need segmented setup. Palettes also work with the base filter. Every preset consists of ordinary options; no effect is reserved for one preset.

Thermal detail modes

The default filter (--thermal luminance) maps luminance directly to the palette, needs no models, and does not segment subjects. The four modes below segment subjects, with different levels of detail. Choose the mode independently of the color palette. Comparison recipe.

Low Detail	Cinematic
Broad, soft silhouettes with reduced anatomical variation and an abstract background.	Broad heat patches, some skin/gear separation, and softer edges.
--thermal low-detail	--thermal cinematic

Detailed	Very Detailed
Distinct skin, clothing, hair, and equipment, with restrained garment shading.	Preserves visible eyes, nose, mouth, hair, and clothing texture through local source contrast.
--thermal detailed	--thermal very-detailed

All four use anatomy-guided fallback when estimates are uncertain. Cinematic, Detailed, and Very Detailed reuse the same models for extra surface segmentation; they take longer as the number of people increases. Very Detailed preserves features that are visible in the input; small, blurred, or obscured faces cannot gain missing detail. Small objects, distant hands, eyewear, and overlaps can still be missed or misclassified.

Yautja style preset

This preset uses eleven colors from black and deep blue through cyan, green, yellow, orange, red, pink, and pale pink-white. It applies 12 thermal levels with soft transitions, dark scenery, a red HUD, cyan annotations, and horizontal CRT lines. Grain and pixelation are off.

Yautja · complete preset	Thermal Spectrum · palette only
--stylepreset yautja	--palette thermal-spectrum

Use --thermal-levels 6 or --thermal-levels 20 for fewer or more bands, --thermal-levels 0 for continuous color, and --thermal-band-softness 0 for hard bands. Soft transitions and optional glow add intermediate visible colors; twelve representative levels does not limit a GIF to twelve RGB colors. Explicit options override the recipe regardless of argument order. For example, add --hud --thermal very-detailed to use its colors and levels with more source detail and overlays. Exact recipe and grading controls.

Focus and Relic style presets

Focus pairs a neon-purple HUD, glyphs and reticle with a blue grid and matching waveform. Straight triangular facets form a slowly rotating geodesic sphere. Broken lines fade toward the center and soften around the waveform, glyphs and readouts. Satellite dots pulse away from vertices and return; some vertices carry seven-sided rings. Thin, partial blue holographic outlines shimmer along detected subjects. One persistent hexagon glides between targets, containing the inset circle, six inner circles, four outer circles and a center square. The Focus preview is at the top of this page.

Relic adds neon hot-pink triangles that emerge below the selected silhouette's center of mass, float upward, then contract and spin away. Soft hot-pink filaments stream upward behind each body's core, aligned to shoulders and hips. When pose information is unavailable, the solid body region supplies the center. Foreground silhouettes hide the trails and their glow. --code-style light selects this treatment; glyphs selects readable code. Focus keeps this effect off. Enable decorative yellow scan patches with --target-weak-spots; both presets leave them off.

Relic

yautja "clip.mov" "focus.mp4" --stylepreset focus --duration 4

yautja "clip.mov" "relic.mp4" --stylepreset relic --duration 4

Use --outline-width, --outline-shine and --outline-speed for the edge treatment. Both presets rotate the sphere gently at 1.8 degrees per second; --geo-grid-rotation adjusts that motion independently of brightness pulses. Relic's --target-motif-* controls tune its ornaments. Focus/Relic guide · Every grid option.

Murphy style preset

Murphy preserves source detail under a slight blue cast. Its bright green HUD uses a centered XY box, selected-subject outline and a medium-weight caption with a blinking underscore. The preview is at the top of the page. Automatic targeting needs no catalog:

yautja "clip.mov" "murphy.mp4" --stylepreset murphy --duration 4

Murphy uses Michroma with a synthesized medium weight. To customize it, add --target-label "SEARCHING" --target-label-scale 2.2 --target-cursor --hud-font michroma-medium --target-scale 1.25. --no-target-cursor holds the caption without a blinking underscore. Complete caption example.

Fremont style preset

Fremont preserves fine source detail under a red/burgundy grade, with white Orbitron Bold text, a moving XY search grid, and bold white subject outlines that blink during analysis. A persistent translucent gray circular target glides between subjects, with a dark inner ring and crosshair. Its size stays constant throughout search, acquisition, and analysis. Descriptions stay inside the screen, including portrait frames. The numbers are decorative; labels describe detected categories such as person, dog, car, or motorcycle.

yautja "clip.mov" "fremont.mp4" --stylepreset fremont

This preset uses the segmented setup above; no figure catalog is needed. Stills show the held analysis immediately. Empty scenes keep the target sweeping in search mode, and cuts or lost tracks restart scanning.

Use --analysis-speed 2 for a faster sequence, --analysis-blink-rate 0 for a steady outline, and --analysis-margin 0.06 for more space at the edges. --analysis-target-size 0.45 enlarges the disk; --analysis-target-response 0.9 makes focus changes more gradual. --no-analysis-target hides just the disk and crosshair, --no-analysis hides the grid/text/outline, and --no-hud hides every overlay. The source highlights are adjustable with --scene-highlights. To scan vehicles, add --warm-objects "person,car,motorcycle,bicycle,bus,truck". Full analysis controls and styling.

Use --hud-font orbitron-medium for medium-weight text and --analysis-outline-width 5 to set outline thickness in reference pixels at a 1080px short edge. These controls save with the style preset.

Ripley

Ripley uses near-black shadows, burnt-orange glyphs and callouts, and a brighter amber waveform. Use the complete preset for the coordinated scene and HUD, or --palette ripley to change only the thermal colors.

yautja "clip.mov" "ripley.mp4" --stylepreset ripley --duration 4

Style presets based on palettes

Yautja is the default palette; Costa Rica uses a blue-to-red ramp. Palette starter presets select Cinematic with the named palette and use the normal defaults for other settings. Use --stylepreset white-hot to select that starter, or --palette white-hot to change colors independently of thermal detail. HUD colors follow each palette's default theme unless customized. These previews include timecode and subject callouts, with identical segmentation and no added texture.

Redline · red, blue, and black	Virtual Boy · red only
--stylepreset redline	--stylepreset virtualboy

Redline gives the movie-style red/blue/black treatment, with broad red warmth and small pink highlights. Virtual Boy uses only red and black, including the glyphs, waveform, and timecode, unless you explicitly choose custom or random HUD colors.

Costa Rica · blue-to-red ramp	Ironbow	Green Phosphor
--stylepreset costa-rica	--stylepreset ironbow	--stylepreset green-phosphor

Amber Phosphor	White Hot	Black Hot
--stylepreset amber-phosphor	--stylepreset white-hot	--stylepreset black-hot

--palette auto selects Yautja. --palette costa-rica selects Costa Rica. Changing thermal detail does not change the palette. Phosphor palettes style the display; they do not recover detail from dark footage.

Abyss and animated heat glow

Abyss uses deep blue-black scenery, amber-to-white-hot regions, and a subdued cyan HUD. Glow is a separate option and is off by default, including with Abyss.

Abyss · clean	Abyss · heat glow
--stylepreset abyss	--stylepreset abyss --heat-glow 0.75

--hud-theme muted-cyan makes the same subdued HUD available with any palette. Selecting --hud-theme palette instead matches its colors to that palette's ramp.

Netrunner style preset

Netrunner keeps the recognizable scene under a dark green tint, with warm-red neon HUD and silhouette outlines, Cyber code raining upward inside detected people and animals, and cyan overhead titles with yellow downward carets. It uses red #FD5550, cyan #41E8EF, and yellow #FFC442. Bold yellow carets keep fixed gaps of 30 reference pixels above the head and 20 below the cyan title, scaled to the frame size. Annotations crop naturally at the screen edge without squeezing these gaps or hiding a still-visible caret. Thin red outlines trace the silhouettes; upward code uses 95% of available columns. It requires the segmented setup above.

yautja "clip.mov" "netrunner.mp4" --stylepreset netrunner

Choose the glyph set independently with --HUDglyphs cyber or --HUDglyphs yautja, or readable --HUDglyphs tech. Cyber contains 192 generated vector glyphs and is the default for Netrunner. The choice applies to every alien HUD readout, waveform glyph, callout, subject title, and code stream; human-readable timecode stays numeric. It also works with other style presets.

yautja "clip.mov" "cyber-thermal.mp4" --stylepreset yautja --HUDglyphs cyber
yautja "clip.mov" "custom-signal.mp4" --stylepreset netrunner --code-speed 1.5 --code-density 0.8

Outlines use flow-aligned, stabilized current-frame masks, with periodic detection and per-frame refinement. This reduces boundary drift during movement, with additional processing time. Titles are decorative labels that stay with a track. A fixed glyph grid lights up in rising streams with bright heads, fading tails, and occasional character changes, clipped within each mask. Glow can extend past the edge. --code-speed 0 freezes the rain. --no-subject-code, --no-subject-outline, and --no-subject-labels switch those parts off independently; --no-hud hides them all. Tracking and occlusion quality depend on the input footage. Complete controls and preset customization.

Customize

Options apply in this order: defaults → optional built-in base → saved settings → explicit flags. Choose one selector, --stylepreset or --preset-file; individual flags win regardless of their position. Supplying a per-element map replaces an inherited map, and omitted elements inherit the relevant global setting. Explicit zero is preserved.

Rendering stage	Options and purpose	Reference
Detect and track	Categories, detection interval, mask stability	Runtime controls
Build the scene	Thermal detail, palette/levels or source tint/exposure	Scene/thermal recipe
Add subject overlays	Outlines, code, titles, carets	Netrunner
Add targeting and grid	Selection, geometry, movement, fill, analysis	Targets · Analysis disk
Draw the waveform	Source → shape → display device → ink	Waveform options
Style HUD artwork	Color, opacity, blur, bloom or neon	Authoritative HUD role table
Finish the picture	Grain, pixels, CRT, VHS, trails	Display recipe

Five different edge controls have different scopes: --subject-outline outlines every detected subject, --target-outline outlines selected subjects, --analysis-outline-width sizes Fremont analysis contours, --target-fill stroked makes the reticle hollow, and --target-stroke adds a colored border to reticle marks. Thermal softness smooths the heat field; HUD blur softens artwork; heat glow lights hot picture regions; HUD bloom/neon lights overlays.

HUD colors, custom palettes, and random colors

White Hot uses a light gray (#D0D0D0) waveform and HUD by default, Black Hot uses black, Abyss uses muted cyan, and other palettes use the standard red/cyan HUD. Use --hud-theme palette to match the waveform, glyphs, clock, callouts, and scale to the selected palette; White Hot keeps light gray ink and Black Hot keeps black ink in this mode too. Use custom or random HUD themes for other color combinations. These controls work with images and videos and every thermal look.

Green Phosphor · matched HUD	Ironbow · matched HUD
--palette green-phosphor --hud-theme palette	--palette ironbow --hud-theme palette

Custom thermal + HUD colors	Random thermal + HUD colors
Exact custom settings	--random-colors --seed 137

Custom thermal colors: use --palette custom --palette-colors "#000000,#0033ff,#ff2200,#fff0c0". Supply 2–16 hex colors, cold to hot, separated by commas or spaces. Stops are evenly spaced. Three- and six-digit RGB hex values work; quote the string.

Custom HUD colors: select a custom theme and assign the desired roles:

yautja "photo.jpg" "custom-hud.png" --hud-theme custom --hud-colors "waveform=#44ff88,timecode=#ddffee,callouts=#88ccff"

Use any key in the HUD role table, including subject, targeting, grid and analysis layers. Omitted elements keep standard colors. Custom ink supports black and dark colors as well as bright ones.

Random colors: --random-colors randomizes both the thermal palette and every HUD element. Use --palette random or --hud-theme random for just one. A different --seed produces a new set; the same seed repeats it. Colors stay fixed throughout the clip. The JSON report includes the resolved hex values so a set can be reused.

See the color controls guide for full commands, element descriptions, and how custom ink interacts with glow and analog effects.

Visual FX

Combine texture, glow, blur, and transparency to style the scene and HUD. Exact comparison recipes explain the settings behind these previews.

Grain and chunky pixels

Every effect is optional. Yautja enables CRT lines by default; use --no-crt-lines to turn them off. The comparisons below use Costa Rica, with other effects off unless shown. Add grain, chunky pixels, CRT lines, or VHS styling independently, or combine them. The heat field, glyph selection, and audio behavior stay the same.

Clean · default	Grain only	Chunky pixels only
No texture flags	--grain 0.06	--pixelation 80

CRT Lines only	Sensor texture · combined preset
--crt-lines	--sensor-texture

VHS only	VHS + CRT Lines
--vhs	--vhs --crt-lines

Bare --grain uses strength 0.035; the example above uses a stronger 0.06 so it is easy to see. --grain 0 disables noise. Bare --pixelation uses a longest grid edge of 96; lower values make larger blocks (range 32–640), and --pixelation 0 disables it. Pixelation changes the display, not the segmentation resolution. --no-crt-lines disables CRT lines.

VHS adds softer color detail, chroma bleed, slight horizontal wobble, tape noise, and occasional dropouts and tracking defects across the finished picture, including the HUD. It animates in video; still images receive a fixed frame of the effect. --no-vhs disables it. It does not alter the soundtrack or invent thermal detail. CRT lines can be used with or without VHS.

The combined sensor preset adds grain 0.035, a grid at --sensor-resolution (default 256), CRT lines, and light intensity quantization. It does not enable VHS. Individual settings override the corresponding preset components. --no-sensor-texture disables the preset while preserving explicitly enabled effects. For completely clean output, omit the effects or use --no-sensor-texture --grain 0 --pixelation 0 --no-crt-lines --no-vhs.

python -m yautja "clip.mov" "outputs/clip-cinematic.mp4" --thermal cinematic --verbose --timecode
python -m yautja "photo.jpg" "outputs/photo-detailed.png" --thermal detailed --palette ironbow --verbose
python -m yautja "clip.mov" "outputs/clip-phosphor.mp4" --thermal cinematic --palette green-phosphor --grain 0.03 --pixelation 96
python -m yautja "clip.mov" "outputs/clip-vhs.mp4" --thermal cinematic --palette redline --vhs --crt-lines
python -m yautja "clip.mov" "outputs/clip-virtualboy.mp4" --thermal silhouette --palette virtualboy

Heat glow, vertical CRT lines, and adjustable trails

Heat glow works with every palette. Set --heat-glow from 0–1 (default 0), and --heat-glow-speed from 0–5 (default 1). A speed of 0 freezes the glow pattern. It brightens and diffuses hot regions before the HUD is added; inverted Black Hot uses dark diffusion. --glow controls HUD bloom independently.

Costa Rica · heat glow	Green Phosphor · heat glow
--heat-glow 0.75	--palette green-phosphor --hud-theme palette --heat-glow 0.75

CRT patterns include vertical lines, a horizontal/vertical grid, and crosshatch (a grid at 45 degrees). --crt-strength sets their darkness from 0–1 (default 0.12); 0 hides them. These patterns affect the complete picture, including the HUD, and work with every palette on images and videos.

Vertical lines	Grid	Crosshatch · 45°
--crt-vertical-lines --crt-strength 0.25	--crt-grid --crt-strength 0.25	--crt-crosshatch --crt-strength 0.25

Grid is equivalent to enabling --crt-lines and --crt-vertical-lines together; combining those flags with grid does not darken the same lines twice. Crosshatch adds two diagonal line directions and can be combined with grid or individual lines. Intersections are darker. Both default off; use --no-crt-grid or --no-crt-crosshatch to disable each independently. The sensor-texture preset enables horizontal CRT lines. Save these settings in your own preset.

Motion blur adds temporal frame persistence: higher values leave longer trails on moving subjects and HUD details. It resets at detected cuts and needs consecutive video frames; stills have no motion trail. CRT bleed adds horizontal phosphor smear to both images and videos. Both strengths range from 0–1, default to 0, and leave the soundtrack unchanged.

Softer motion trails	Stronger motion trails
--motion-blur 0.35	--motion-blur 0.85

Softer CRT bleed	Stronger CRT bleed
--crt-bleed 0.3	--crt-bleed 0.85

All of these controls are independent of VHS, grain, pixelation, and the sensor-texture preset.

Neon HUD

Add --neon to illuminate waveform artwork, glyphs, timecode, callouts, leaders, markers, and selected targets. A bright core and two soft halos follow each element's color. Neon is off by default and works with every palette, for images and video.

Steady neon	Neon hum
--neon	--neon --neon-flicker 0.5

The Abyss target example also uses neon: its muted #267085 ink emits a brighter cyan halo.

Control	Meaning
--neon / --no-neon	Enable or disable the entire treatment; default off
--neon-intensity 1	Brightness from 0–2; default 1. Zero shows the ink without a neon halo
--neon-spread 0.6	Halo spread from 0–2; default 0.6. Lower values give a tighter rim
--neon-flicker 0.5	Synchronized seeded hum from 0–1; default 0 is steady
--neon-elements "waveform=0.6,target=1.2,timecode=0"	Independent intensity overrides; omitted elements inherit the shared value

Element names are shared with HUD blur; target covers both flash states. Color, outlines, blur, and opacity also affect neon artwork. Blur softens the core; opacity fades both core and halo. White Hot glows white, Black Hot diffuses black, and Virtual Boy uses red ink. --heat-glow is independent. Neon replaces standard --glow bloom while enabled, and CRT/VHS effects run afterward. --no-hud hides all of it.

Load or customize the bundled Abyss Neon preset with --preset-file. Save neon settings with --save-preset. Full controls.

Reticle stroke and HUD blur

Add an optional outline with --target-stroke 5. Choose one outline color or a landing/flash pair with --target-stroke-colors "#660b12,#687a8d"; omit the colors to use darker shades of the current target colors. The outline is drawn inward, keeping the corner gaps open. It is off by default (--target-stroke 0); the bare flag uses width 2 and the range is 0–12.

--hud-blur 3 softens all HUD artwork. Use --hud-blur-elements "waveform=6,target=4,timecode=0" for independent overrides: omitted elements inherit the shared amount, and explicit 0 keeps an element sharp. Every radius is 0–20, with 0 as the default. Blur and stroke widths are pixels at a 1080px short edge, scaled with output size. HUD blur affects the artwork before it is placed on the scene, leaving the underlying thermal image sharp.

Reticle outline · separate flash colors	Target blur only
--target-stroke 5 --target-stroke-colors "#660b12,#687a8d"	--hud-blur-elements "target=8"

Matched red · waveform + reticle blur	Shared HUD blur · sharp timecode
--wave-style rorschach --wave-width 0.14 --wave-height 1 --hud-blur-elements "waveform=6,target=6"	--hud-blur 3 --hud-blur-elements "waveform=6,target=5,timecode=0"

Choose blur keys from the HUD role table, including waveform, target, and timecode. Target blur applies to both flash states. These controls work for images and videos, alongside HUD bloom, heat glow, and CRT/VHS effects. --no-hud hides them all. Full controls and examples.

The matched-red Rorschach example additionally uses --hud-theme custom --hud-colors "waveform=#ff302b,timecode=#ff302b" --target-colors "#ff302b,#ff302b". Both reticle states use the same red. Custom HUD colors use alpha compositing, avoiding the pink shift that screen blending can introduce over a blue scene.

HUD transparency

Set --hud-opacity 0.5 for half-strength HUD artwork, or --hud-opacity-elements "waveform=0.3,target=0.7,timecode=0.9" for separate values. 0 is invisible; 1 is full opacity (the default). Omitted elements inherit the shared opacity; explicit values override it. Blur and opacity are independent, and both work for stills and videos.

Entire HUD · opacity 0.5	Independent opacity · waveform / target / timecode
--hud-opacity 0.5	--hud-opacity-elements "waveform=0.3,target=0.7,timecode=0.9" with the matched red Rorschach colors and shape above

Independent opacity · neon on
Add --neon to the independent-opacity example above

This keeps the Costa Rica thermal colors, red waveform/target/timecode, cyan callouts, and the same opacity values: waveform 0.3, target 0.7, and timecode 0.9. Neon adds bright cores and soft halos to the HUD; both target states stay red.

The HUD role table lists every opacity key, including subject, grid, and analysis layers. A target override controls both states unless target-flash is explicitly set. Reticle outlines and glow follow their element's opacity. --no-hud hides everything. Detailed transparency controls.

Turn the HUD off

Use --no-hud for the thermal image alone. It removes the waveform, scale, glyphs, timecode, callouts, connector lines, and target markers—even when --timecode or --verbose is also supplied. Thermal style, palette, textures, and the video soundtrack stay active. HUD is on by default; --hud turns it back on.

HUD on · default	HUD off
Default HUD, with --verbose --timecode for annotations and clock	--no-hud

With --verbose, callout lines aim at a smoothed center of each visible silhouette—an image-based approximation of center of mass. Labels keep their position relative to the figure while that space remains clear, reducing jumps between moving arms and shoulders. If the center falls outside a concave or partly hidden silhouette, the marker uses the nearest visible point. This is automatic; no extra flag is needed.

python -m yautja "clip.mov" "thermal-only.mp4" --thermal cinematic --no-hud
python -m yautja "photo.jpg" "thermal-only.png" --palette green-phosphor --no-hud

Waveforms

Choose a Rorschach inkblot or one of three digital distortion waveforms. These examples use Redline, with --wave-width 0.14 --wave-height 1 --wave-gain 4 (extra audio gain for this quiet clip); the narrower Vocoder Bars example uses --wave-width 0.09. The illuminated shape follows the soundtrack; GIFs are silent.

Filled · broad connected lobes	Split · separated inkblots	Hollow · dark interior pockets
--wave-style rorschach	--wave-style rorschach-split	--wave-style rorschach-hollow

The digital styles use distinct geometries: stacked blocks with square cutouts, scattered data packets, or horizontal vocoder bars in one narrow vertical stack. The vocoder spans the frame height along the left edge; each rounded, dark bar contains small vertical LED segments, brightest at the center and fading toward the ends. Audio lights up vivid red segments across alternating shorter and longer rows, with an exaggerated response and a strong red halo. Inactive segments remain visible in dark burgundy fading to black, including during silence. Its red glow is inspired by KITT’s voice display.

Bitcrush Blocks	Packet Shards	Vocoder Bars
--wave-style digital-blocks	--wave-style digital-shards	--wave-style digital-circuit

--wave-width sets maximum width as a fraction of the frame (0.02–0.3, default 0.12); --wave-height sets height (0.1–1, default 0.96). In Rorschach styles, --wave-detail goes from broad and smooth at 0 to sharper edge spikes and more intricate lobes at 1 (default 0.6). These shapes keep a thick mirrored core, with pointed, irregular edges driven by short peaks and troughs in the waveform. Quiet ambience is amplified for visibility, and louder audio fills more of the column. Silent pauses within audible tracks stay empty; an absent or entirely silent soundtrack uses a procedural waveform.

In Blocks and Shards, --wave-detail controls pixel density: lower values make larger chunks, higher values make finer blocks. In Vocoder Bars it controls the number of horizontal rows. The casings and idle segments stay fixed while audio expands and brightens the active segments. Silence leaves the dim inactive bars visible. The vocoder preview uses --hud-theme custom --hud-colors "waveform=#FF302B" and --neon --neon-intensity 0 --neon-elements "waveform=1.2" --neon-spread 0.4 --neon-core-whiten 0 for bright red active segments with a strong glow. Inactive segments use a dim version of the chosen waveform color and emit no light. The dark casing shares waveform opacity and blur, and emits no light; color and neon are configurable. --wave-style trace is the default. All six styled waveforms replace the left trace, scale, and flanking glyph rows. They use the waveform color, work with all HUD themes, blur, opacity, and neon, and leave timecode, callouts, and selected targets intact. Combine --crt-bleed 0.3 for softer edges or --motion-blur 0.4 for video trails.

Shape and display are independent. --wave-style chooses any of the seven shapes; --wave-display plain|led chooses direct ink or a segmented LED device. Digital Circuit defaults to LED, the others to plain. --wave-backlight controls non-emissive idle cells from 0–1; use 0 to hide both the idle cells and their housing so the background shows through. LED device materials follow waveform ink, opacity and blur; only active cells emit bloom/neon. Trace keeps its axis, ticks and glyphs plain.

yautja "clip.mov" "led-rorschach.mp4" --wave-style rorschach --wave-display led --wave-backlight 0 --hud-theme custom --hud-colors "waveform=#ff302b" --neon --duration 1

The same Rorschach shape rendered as an LED display: glowing red active cells with the scene visible through the inactive areas. Exact preview recipe.

Target shapes

All 11 target types support --target-fill filled and --target-fill stroked. Filled mode uses solid marks and dots, with translucent interiors for enclosed reticles. Stroked mode traces their edges, including hollow dots, curved bands, crosshairs, and square brackets. The default auto uses each design's default treatment. Color, acquisition timing, flash, glow, blur, and opacity are independent; --target-stroke adds an optional colored border.

Triangle + three lock dots	Circle + three lock dots
--target-shape triangle-dots	--target-shape round-dot

The three dots appear on lock and reset when the target is lost.

The complete contact sheet includes all 11 geometric shapes, including both lock-dot designs, plus Fremont's scan disk. Each appears filled on the left and stroked on the right. Geometric labels give the corresponding --target-shape value. Fremont uses --analysis-target and the same --target-fill control; its stroked version traces the outer circle, inner circle and crosshair. Both Fremont samples are red for this PNG; the preset uses translucent gray fill and dark marks. Its controls are explained in the analysis guide.

yautja "clip.mov" "filled.mp4" --stylepreset yautja --figures "figures.json" --target S001-F002 --target-shape triangle-dots --target-fill filled
yautja "clip.mov" "stroked.mp4" --stylepreset yautja --figures "figures.json" --target S001-F002 --target-shape square-cross --target-fill stroked

triangle is the default; --target-scale changes the reticle size. Hollow Cross has four L-shaped bands and an open center. --target-mode auto uses segmented subjects automatically, while the default selected mode uses a catalog. Explicit catalog selections take precedence, including frames where a selected figure is absent. --target-motif triangles and --target-label "TARGETING" add ornaments and a caption. Full selection, color, and effect controls.

Choose a figure and add a target

Scan a clip or still to get a shot-by-shot figure list, thumbnails, and reusable IDs. Scanning needs the segmented setup. Open the generated contact sheet, choose an ID, then render:

yautja "clip.mov" "figures.json" --list-figures
# Open figures.html; select an ID from that scan.
yautja "clip.mov" "targeted.mp4" --thermal cinematic --figures "figures.json" --target S001-F003

The saved catalog belongs to the exact source file. Reuse it for different palettes, resolutions, frame rates, or trims; select additional shot IDs explicitly when a figure reappears after a cut. IDs are detected tracks, and detection can miss or swap figures during occlusion. Inspect the contact sheet and output. targets_seen and targets_unseen in the report confirm which selections appeared.

Assemble and flash · red/white	Abyss · glowing cyan target + vertical CRT	Custom target colors
Default target animation	--palette abyss --target-colors "#267085,#267085" --no-target-flash --neon --crt-vertical-lines --crt-strength 0.25 --heat-glow 0.65	--palette green-phosphor --hud-theme palette --target-colors "#31d7bb,#d6fff3" --target-acquire 0.45 --crt-bleed 0.4

The triangle contracts into a compact marker at the figure's center, with solid-color sides and narrow, clear gaps at all three corners. It assembles in 0.8 seconds, lands red, then flashes red/white at 1.5 cycles per second. Set --target-acquire, --target-scale, and --target-flash-rate to change timing and size; scale 1 uses the compact reticle. --no-target-flash keeps the assembly and holds the primary color; equal primary/flash colors work too. White Hot uses light gray and Black Hot uses black for both target states unless colors are overridden. Stills display the assembled triangle immediately.

Set --target-colors "#ff302b,#ffffff" for independent primary/flash colors, or use the target and target-flash keys with custom HUD colors. Palette-matched and random HUD themes also color targets. --no-hud hides them along with every other overlay. All target controls, bounds, scan details, and effect options.

Save, load and share

Save a full portable snapshot of visual settings. Bundled font names are saved; custom font paths, media paths, catalog IDs, timing, encoding, audio selection and model/device/mask-runtime settings are chosen per conversion. Saving needs no media or models.

yautja --stylepreset yautja --thermal luminance --hud-theme palette --neon --save-preset "readme-style.json" --preset-name "My Style"

yautja "photo.jpg" "readme-reused.png" --preset-file "readme-style.json" --heat-glow 0.2

Share the JSON and load it with --preset-file. Exported snapshots include resolved defaults; hand-authored JSON can instead name a base and list only its changes. Existing files require explicit --overwrite. Schema and full round trip · List built-ins.

Tropic Glow · Yautja with neon HUD and heat glow
Editable JSON preset · Creation, schema, and sharing guide

Tropic Glow editable JSON combines Yautja with palette-matched neon and heat glow. Detailed comparison.

Control the output

Keep aspect ratio with --max-size; set a frame rate with --fps, or omit it to retain the source rate. Trim with --start and --duration. Lower --crf means higher quality and larger files; encoder --preset slow spends more time compressing. It is unrelated to visual --stylepreset.

yautja "clip.mov" "quality.mp4" --start 0 --duration 1 --max-size 1280 --fps 24 --crf 18 --preset slow --audio-stream 0

For a quick check, use --max-size 640 --fps 12 --crf 24 --preset fast --duration 1, then remove the preview limits for the final export.

Sound is retained by default. --audio-stream 1 selects the second audio track for both playback and waveform analysis. --mute removes playback but keeps analysis. Auto waveforms use procedural motion when audio is absent or silent; --waveform audio requires an audio track and preserves silent samples. With nonzero backlight, LED idle cells remain visible during silence. Stills always use procedural waveform sampling; timing/encoding/audio options intended for video are inactive or rejected where inappropriate. Output and audio examples.

Troubleshooting

Symptom	Cause and next step
Models are missing	Install yautja[semantic], then run yautja --download-models once. Ordinary conversion does not download.
Video fails before conversion	Run yautja --doctor; put both FFmpeg and ffprobe on PATH. Image diagnosis uses --media image.
A preset requires segmentation	Its subject overlays require segmentation. Install the semantic extra, or use only its palette with --thermal luminance --palette ….
Target is missing	Automatic targeting needs segmented subjects; explicit targets need a catalog from the exact input file. Check targets_seen and targets_unseen in the report.
Outline flickers around small accessories	Defaults stabilize masks. Tune --mask-stability and --mask-min-region; setting both to zero disables stabilization.
A label reaches the frame edge	Fremont descriptions and target captions fit safe margins. Overhead Netrunner glyph titles intentionally crop while preserving head/caret spacing.
Styling appears unchanged	Check its enabling flag, --no-hud, element opacity and preset precedence. Nonzero neon settings require --neon.
Output already exists	Choose another output path or explicitly add --overwrite. Replacement happens after successful conversion.
CLI uses the wrong environment	Run python -m yautja --doctor with the same Python used for installation; inspect its installation report.

The same seed repeats procedural artwork for the same inputs and settings. Model/device/precision differences, codec conversion and source changes can still alter output; this is not a cross-platform pixel guarantee. Runtime and codecs · Segmentation details.

Install the agent skill

The Yautja skill lets Claude Code or Codex operate the local converter. The Quick start installer lets you choose your agents and installation scope. To install globally for both agents:

npx skills add petehottelet/yautja --skill yautja --agent claude-code codex --global

Then ask: “Use Yautja’s Cinematic look with the Costa Rica palette, glyph callouts, timecode, and the source audio. Keep the image clean.” The skill reuses a compatible installed runtime, checks prerequisites, and guides segmentation setup when needed.

You can also use the CLI directly in your terminal or scripts.

The installer copies only skills/yautja/; it does not copy the converter or gallery. If the runtime is missing, the skill installs it separately from PyPI in a suitable environment. Release bundles include yautja-skill.zip with the matching application wheel; offline setup also requires dependency wheels and, for segmentation, model caches.

Local skill bundles and updates

Use python -m pip install --upgrade yautja in the environment you installed into, or retain the extra with python -m pip install --upgrade "yautja[semantic]". For pipx, use pipx upgrade yautja. Run yautja --version and yautja --doctor afterward. Update agent instructions through the installer you used and restart the agent session. Neither conversion nor a skill update silently upgrades the other component.

Release bundles include a matching wheel; offline use also requires a compatible dependency wheelhouse and separate model caches/FFmpeg. Offline instructions · Local skill builds.

Reference, licensing and contributing

• Every CLI option, default, alias and example
• Runnable examples and HUD element roles
• Additional gallery detail, Python API, changelog and roadmap
• Development, tests and gallery regeneration and publishing

Code and original glyph artwork are MIT licensed. Bundled Michroma and Orbitron fonts retain their OFL licenses. Downloaded model weights carry their own licenses, described in the dependency guide. The int10h font pack is not bundled. Bring only fonts you are licensed to use through --hud-font-file.

Contributions are welcome through issues and pull requests. Include a small reproducible example and verification for a changed visual behavior. Private plans and source demo footage are excluded from releases.