oledgifstudio 0.1.2

Générateur de GIFs animés 1 bit pour écrans OLED (SteelSeries, SSD1306, ...)

oled-gif-studio

Lire en français

1-bit animated GIF generator for small OLED screens: SteelSeries keyboards/mice, SSD1306/SH1106 modules (Arduino, Raspberry Pi, QMK macropads)...

No AI model, no paid API: everything is procedural (Python + Pillow), so it's instant, free, and pixel-perfect. A "natural language description" mode (French or English) picks the effect and parameters for you.

All previews in this README are scaled ×3 — the actual GIF size is that of the target screen (128×40 by default).

Installation

None needed if Python (≥ 3.10) + Pillow are already installed. Otherwise:

pip install Pillow

Optional, to get the oledgif command available everywhere:

pip install -e .

Quick usage

# From the project folder:
python -m oledgif "HELLO WORLD"                          # auto effect → hello.gif
python -m oledgif "GG" -e slot -o gg.gif                 # slot machine
python -m oledgif "PWNED" -e glitch -p rival             # for a mouse's OLED
python -m oledgif "42" -e matrix --size 128x64 --fps 20  # custom size

# In natural language:
python -m oledgif -d "the text 'HELLO' scrolling slowly"
python -m oledgif -d "'GAME OVER' blinking fast for 3s"
python -m oledgif -d "a radar sweeping the screen"

# From an image:
python -m oledgif -i photo.jpg --fit cover               # full-screen photo, vhs effect
python -m oledgif -i comic.jpg --fit cover --style comic # illustration/comic
python -m oledgif -i logo.png -e bounce                  # the logo bounces
python -m oledgif -i meme.gif                            # animated GIF converted as-is

# Text-free patterns (screensavers):
python -m oledgif -e starfield
python -m oledgif -e plasma --seconds 6

# One example of every effect in ./samples:
python -m oledgif --demo

Text / image effects (--list-effects)

scroll — perfectly looping scroll	typewriter — typewriter with cursor
wave — letters waving	blink — blinking
bounce — DVD-logo-style bounce	matrix — character rain revealing the text
slot — each letter cycles then locks in	glitch — shifted bands + noise
pulse — heartbeat	vhs — VHS tape tracking look
slide — bottom-to-top credits crawl

typewriter, wave, matrix, and slot are text-only; the others also accept an image (--image).

--effect auto (default): scroll if the text is too wide for the screen, otherwise wave; vhs for an image; direct conversion for an animated GIF.

Text-free patterns (screensavers)

starfield — hyperspace	plasma — retro dithered plasma
life — Conway's Game of Life	eq — audio equalizer
scope — oscilloscope	radar — sweep with echoes

Images: the 4 rendering styles

Converting a color image to 1 bit over 5120 pixels is an exercise in sacrifice — the right --style depends on the source. Demonstrated on the same scene (moon, silhouettes against a gradient sky, city lights):

Render	Style
	Source (grayscale)
	--style photo (default) — auto-contrast + sharpening + Floyd-Steinberg dithering. The right choice for real photos: the dithering simulates grayscale levels. On an illustration it turns into noise.
	--style solid — hard thresholding (alias --no-dither). Great for logos and line art… but anything dark-on-dark disappears into black.
	--style comic — like solid, but an automatic 2nd threshold (Otsu) separates dark tones and outlines shapes drowned in black with a white contour. Ideal for illustrations/comics.
	--style edges — edge detection, white lines on black background. Neon/wireframe look, often the most readable for a landscape or a face.

Other image options:

• --fit cover — the image fills the whole screen (cropped) instead of being shrunk to a stamp in the middle. Recommended for landscape photos.
• Denoising (on by default): a median filter plus isolated-pixel removal eliminate "salt and pepper" noise (reflections, streetlights, stars). --no-denoise disables it if you actually want to keep those specks.
• An animated GIF input is converted frame by frame, keeping the original durations (with --effect auto).

Natural language (--describe)

python -m oledgif -d "the text 'BRB' bouncing for 5 seconds"
python -m oledgif -d "'REC' in vintage vhs mode"
python -m oledgif -d "un radar qui balaie l'écran"

The parser (FR/EN, accent-insensitive) recognizes the effect by keywords ("scrolls", "blinks", "types", "radar", "vintage"...), the text in quotes, the duration ("for 3s"), and the speed ("slowly", "fast").

Preconfigured screens (--list-presets)

Preset	Size	Hardware
apex (default)	128×40	SteelSeries Apex 5 / 7 / Pro (keyboard OLED)
rival	128×36	SteelSeries Rival 700 / 710 (mouse OLED)
oled-128x64	128×64	SSD1306 / SH1106 / SSD1309
oled-128x32	128×32	SSD1306
oled-96x16	96×16	SSD1306
oled-256x64	256×64	SSD1322

Any other size: --size WIDTHxHEIGHT.

Useful options

• --charset alnum|digits|upper|letters|ascii or a literal string — the character set used by matrix and slot (default: the 62 alphanumeric characters 0-9A-Za-z).
• --font path.ttf --font-size N — custom font (default: Consolas, size adjusted to the screen).
• --invert — black on white.
• --scale 4 — GIF enlarged ×4 (for comfortable previewing).
• --seed 42 — reproducible rendering for random effects.
• --fps, --seconds, --speed (px/s for scroll).

Sending the GIF to a SteelSeries screen

Two options:

1. SteelSeries GG: in your keyboard's settings (OLED section), you can import a 128×40 image/GIF — the GIFs generated here are already in the right format (1 bit, exact size).
2. GameSense API (programmatic): like SteelseriesAnimGif does, you can stream frames to the screen via SteelSeries GG's local API. The GIFs produced here are directly usable frame by frame.

Project structure

oledgif/
  cli.py        # command line + make_gif()
  effects.py    # the 11 text/image effects (@effect registry)
  patterns.py   # the 6 text-free patterns
  render.py     # image prep, binarization, GIF writing
  describe.py   # FR/EN natural language parser
  presets.py    # market screen sizes
  fonts.py      # font loading
samples/        # one example GIF per effect (actual size, --demo)
docs/           # README illustrations (scaled ×3)

---

My pick

Ninja Turtles!