halftone-fx

Live GPU halftone dithering for websites — help & embedding guide

halftone-fx renders an image or video as animated halftone dots, live in the browser, on the GPU. Instead of exporting a heavy video file, you embed a tiny program: it stays razor-sharp on any screen, costs ~0.1 ms of CPU per frame, and a whole animated hero background weighs a few hundred kilobytes.

Quick start

Open the playground.
Pick a clip from Source (the list mirrors this repo's webgl/assets/ folder) and tune the sliders until it looks right.
Click 📋 Export iframe — the finished embed code is copied to your clipboard.
Paste it into your site builder's embed/HTML element. Done.

Embedding in STUDIO (studio.design)

In the STUDIO editor, open the 追加パネル (Add panel) on the left and add an 埋め込みボックス (Embed box) to your page.
Select the box, open the settings panel on the right, and paste the code from Export iframe into the 埋め込みコード (embed code) field.
Size and position the box like any element — for a hero background, make it fill the section and layer your text boxes on top.
The editor canvas may show a placeholder instead of the animation — that's normal. Check プレビュー (preview), then 公開 (publish).

Keep the embed box to the single <iframe> tag. A standalone iframe gets STUDIO's clean "iframe type" embed; any extra HTML around it switches STUDIO to a restricted sandbox mode.

Backgrounds: the exported code includes pointer-events:none so clicks and scrolling pass through to your page. Remove it if the animation should be interactive. Set the bg param to your page's background color so the iframe edges are invisible.

URL parameters

The embed page is configured entirely by its URL — edit params and reload to restyle, no code changes ever:

https://playbox-dev.github.io/halftone-dithering-fx/webgl/embed.html?src=./assets/horse.mp4&grid=9&dither=grain

Param	Values	Meaning
`src`	URL	Image or video. Relative (`./assets/…`) or any CORS-accessible absolute URL. Add `type=video` for video URLs without a file extension.
`grid`	3–50	Halftone cell size in px. Smaller = finer dots. Default 12.
`dot`	hex	Dot color, without `#` (e.g. `1a1a2e`). Default black.
`bg`	hex / `transparent`	Background color. Default white.
`brightness`	-100…100	Default 0.
`contrast`	-100…100	Default 0.
`gamma`	0.1–3	Default 1.
`dither`	`none` `bayer4` `bayer8` `grain` `noise`	See dither modes. Default none.
`multicolor`	flag	Rainbow dots colored by brightness.

Adding your own image / video

Assets live in the repo, so they're versioned and served with correct CORS headers. To add one:

Open webgl/assets on GitHub → Add file → Upload files → commit.
Wait ~1 minute for GitHub Pages to redeploy.
Reload the playground — the file appears in the Source dropdown automatically (the list is read live from the repo).

Keep files small — it's free. The halftone destroys fine detail, so a 640×360 heavily-compressed clip looks identical to 1080p. The dots are drawn by the shader and stay sharp regardless. Recommended encode:

ffmpeg -i input.mp4 -vf scale=640:360 -c:v libx264 -pix_fmt yuv420p \
       -crf 30 -preset veryslow -movflags +faststart -an output.mp4

The two bundled clips are 97 KB (spiral) and 373 KB (horse).

Dither modes

For animation, temporal stability is what matters — a pattern that changes every frame reads as shimmer. All modes are stable except noise, which flickers on purpose:

Mode	Look
`none`	Smooth tonal halftone — dot size carries the tone. Best default.
`bayer4`	Coarse retro print / CRT crosshatch.
`bayer8`	Finer retro pattern, more tonal steps.
`grain`	Organic, editorial — blue-noise-like, no visible pattern.
`noise`	Animated film grain, re-seeded ~30 fps.

Error-diffusion dithers (Floyd–Steinberg, Stucki…) are deliberately absent here: they're sequential (can't run on a GPU shader) and they shimmer on video. They live in the classic export tool for still images.

Performance

Measured head-to-head against the CPU original (same video, 1920×1080, Apple M2 Pro): CPU version 51.7 ms/frame (~19 fps max, one core pinned) vs WebGL ~0.07 ms/frame — about 700× faster, using under 1% of a 60 fps frame budget. Reproduce it: open bench.html, wait a few seconds, and read window.__results in the console.

FAQ

The animation doesn't show inside the STUDIO editor.
Expected — embeds render in preview and on the published site, not on the editor canvas.

bg=transparent looks white when I open the embed URL directly.
Expected — a standalone browser tab has nothing behind the page, so you see the browser's own default backdrop. The transparency is real: put the iframe on a page (or in STUDIO) and the page shows through between the dots. Both bg and background work as the param name.

The video doesn't autoplay.
Keep allow="autoplay" on the iframe. Playback is muted + inline, which all browsers permit.

Colors in the URL don't work.
Drop the # — write dot=ff3300, not dot=#ff3300.

Can I use a clip hosted elsewhere (not in this repo)?
Yes, if the host sends CORS headers (Access-Control-Allow-Origin). GitHub Pages does; most random hosts don't. When in doubt, commit it to webgl/assets/.

Does it work on phones?
Yes — WebGL2 is supported by all current browsers including iOS Safari, and the effect is far lighter than a CSS blur. The component also pauses itself when scrolled offscreen.