Want Khayalon Ki Duniya (खयालों की दुनिया, "world of thoughts") to come alive on a tiny 0.96" SSD1306 OLED? This project plays a full 124-frame mono animation loop using Adafruit SSD1306. It works for your desk toys, classroom demos, Hindi song-themed builds and GIF-to-OLED experiments.
⬇ Free download, Khayalon Ki Duniya OLED code
You get the full main.ino with all PROGMEM frames · ZIP or git clone
Parts list
- Board: ESP8266 NodeMCU / Wemos D1 Mini, ESP32 or Arduino Mega (I'd pick one of these)
- Display: 0.96" SSD1306 I2C OLED, 128×64. Yours usually answers at
0x3C - 4 Dupont wires (VCC, GND, SDA, SCL)
- A USB cable and Arduino IDE
Connection / wiring
Match your board. If you get SDA/SCL wrong, you'll see a blank screen.
| OLED pin | Arduino Uno / Nano | ESP8266 (NodeMCU) | ESP32 |
|---|---|---|---|
| VCC | 5V (or 3.3V if module requires) | 3.3V | 3.3V |
| GND | GND | GND | GND |
| SDA | A4 | D2 (GPIO4) | GPIO21 |
| SCL | A5 | D1 (GPIO5) | GPIO22 |
On ESP8266, call Wire.begin(4, 5) before display.begin() if the default I2C pins fail. If your screen stays black, try address 0x3D and read
OLED blank screen fixes.
Libraries
- Arduino IDE → Tools → Manage Libraries
- Install Adafruit SSD1306
- Install Adafruit GFX Library
- Select your board and the right COM port
How the player works
You'll find all frames stored as const uint8_t PROGMEM frameN[1024] from frame0 through frame123. In loop() the sketch moves the index forward on a timer and draws the current bitmap:
void loop() {
static uint8_t frameIdx = 0;
static unsigned long lastMs = 0;
const uint8_t* frames[] = { frame0, frame1, /* ... */ frame123 };
const uint8_t numFrames = 124;
if (millis() - lastMs >= 67) {
lastMs = millis();
display.clearDisplay();
display.drawBitmap(0, 0, frames[frameIdx], 128, 64, SSD1306_WHITE);
display.display();
frameIdx = (frameIdx + 1) % numFrames;
}
}
Change 67 to speed up or slow down the loop. Smaller means faster FPS (for example, 100 ≈ 10 fps and 67 ≈ 15 fps). The full loop takes about 8.3 seconds.
Upload & run
- Open khayalokiduniya and download the ZIP, or clone it
- Open
main.inoin your Arduino IDE - Install Adafruit GFX + SSD1306 if you haven't already got them
- Pick your ESP8266 / ESP32 / Mega and COM port
- Click Upload
- Watch Serial at 115200. If you see
SSD1306 allocation failed, fix your power, wiring or address
Ready to flash?
Grab the complete Khayalon Ki Duniya main.ino from GitHub now.
Make your own song animation
I exported Khayalon Ki Duniya from oledanimationmaker.com, and you can do the same:
- Open the free tool in Chrome or Edge
- Go to Import and drop in a short GIF or video clip
- Tune the FPS and frame count to fit your board's flash
- Click Get the Code and choose Adafruit SSD1306 Arduino
- Paste it into your IDE, or push it to your own GitHub
Related guides: GIF to OLED, Image to byte array, SSD1306 animation basics, Kalayani song OLED.
Troubleshooting
- Sketch too big, so use an ESP8266/ESP32 or cut some frames
- Blank OLED, so use 3.3V on an ESP, check your SDA/SCL and try
0x3D - Slow / laggy, so keep your frame delay at 50-80 ms or more and use solid USB power
- Compile OOM, so on ESP8266 set a higher flash size in Tools
- Garbage at end of file, so delete any stray characters after the last
}inmain.ino
FAQ
Is the Khayalon Ki Duniya OLED code free?
Yes, it's free. You'll find it at github.com/itzmeAshish/khayalokiduniya.
Will I hear audio from it?
No, it's a visual OLED animation only. If you need sound, you'll have to add a speaker separately.
Can I change the clip?
Yes, you can. Import a different GIF/video into OLED Animation Maker and export a new sketch.
What does Khayalon Ki Duniya mean?
It's Hindi for "world of thoughts." The sketch you'll upload is a 124-frame visual loop at ~15 fps, about 8.3 seconds per cycle on a 0.96" SSD1306.
Build more OLED song & GIF animations
You get a pixel editor, GIF import, WebSerial live preview and Arduino & MicroPython export. It's free in your browser.
Open OLED Animation Maker →What main.ino contains for this Hindi loop
Clone itzmeAshish/khayalokiduniya
and you get one sketch: main.ino. The Hindi title on the page is Khayalon Ki Duniya (खयालों की दुनिया), "world of thoughts." The file doesn't store lyrics, a singer credit block or an audio sample. It stores the visual loop: frame0 through frame123, 124 arrays, each
const uint8_t PROGMEM ... [1024]. setup() brings up your SSD1306 at 0x3C and prints to Serial at 115200 if allocation fails.
loop() calls drawBitmap(0, 0, ..., 128, 64, SSD1306_WHITE)
and then display().
Because the file is main.ino, the folder on disk must be named main, since Arduino IDE compares those two names. A ZIP that unpacks to khayalokiduniya-main will prompt you to move the sketch, so you should rename that folder to main before your first compile. Don't rename the file to code.ino unless you rename the folder too. This repo uses the main layout, unlike the Kalayani repo.
Speed table for the 67 ms step
Stock timing is 67 ms, about 15 fps. A full cycle is 124 × 67 ms = 8,308 ms, which is the 8.3 seconds I quoted above. That's a short, smooth loop compared with the slower song players on this site, and it's close to the time you need to ship a full frame over I2C.
| Delay | Approx. fps | 124-frame cycle | I2C note |
|---|---|---|---|
| 134 ms | ~7.5 | ~16.6 s | Easy on the default 100 kHz bus |
| 100 ms | 10 | 12.4 s | Still fine for most modules |
| 67 ms (stock) | ~15 | 8.3 s | Works best if the bus can finish a 1024-byte transfer in time |
| 50 ms | 20 | 6.2 s | Usually limited by display() itself, not by the number you typed |
At 100 kHz, 1024 data bytes plus ACK bits take roughly 90 ms on the wire. A 67 ms test can expire while display() is still clocking the previous frame, so the picture moves as fast as the bus allows and the 15 fps label becomes a target. If your motion looks slower than 8.3 seconds per pass, add Wire.setClock(400000); after the bus starts. At 400 kHz the same payload takes roughly 25 ms, and the 67 ms step is real again. Don't set the clock before Wire.begin().
Pins and power for a 15 fps bitmap
The generated header mentions Uno (SDA A4, SCL A5). Treat that as the pin legend for a short test. It doesn't mean you can compile 124 KB of frames for a 32 KB Uno. For the published sketch:
- ESP8266 NodeMCU / Wemos D1 Mini: 3.3V to VCC, GND to GND, D2 (GPIO4) to SDA, D1 (GPIO5) to SCL. Call
Wire.begin(4, 5)if your board package doesn't pick those pins. - ESP32: 3.3V, GPIO21 for SDA and GPIO22 for SCL. ESP boards don't use the 5V pin to run your OLED.
- Uno or Nano, only after you cut the frame count: 5V is fine on modules that have a regulator. Use SDA A4, SCL A5 and address 0x3C.
A fast loop makes a weak USB cable obvious. If your panel browns out every few seconds, the 15 fps refresh is pulling the rail down. Shorten the cable, or power the board from a charger that can hold 5V at the USB socket. Your OLED still wants 3.3V on an ESP.
124 KB is why the Uno line in the header misleads
Do the math: 124 frames × 1024 bytes = 126,976 bytes, about 124 KB of flash for the pictures alone. Classic Uno and classic Nano stop near 32 KB total, and you'll see the compiler error before any pixel is drawn. A Mega 2560 (256 KB flash) can be in range after libraries. An ESP32 or a 4MB ESP8266 is the straightforward choice, and it's the one I'd use. Set the flash size in Tools so the build isn't aimed at a 1MB layout with a large SPIFFS slice that steals the bitmap space.
Slowing the delay doesn't shrink the binary. If you need an Uno, I'd re-export a handful of frames from the maker and keep this 124-frame file for your ESP. Don't paste half of main.ino into an empty sketch, because that usually breaks the pointer list that loop() indexes.
How to change the delay without losing the cycle
The only timing constant you need to touch is 67 in
if (millis() - lastMs >= 67). Replace it, leave numFrames at 124, and upload. The wrap
frameIdx = (frameIdx + 1) % 124 (via numFrames) is what makes the 8.3 second visual repeat. You won't get an end screen.
For a calmer desk loop, 100 or 134 ms is the change I'd make first. You keep every bitmap, you give the bus a full transfer window, so you don't need setClock just to look smooth. For a recording, 100 ms gives you a 12.4 second pass, which is easier to film than a loop that laps your camera's start button.
Filming one 8.3 second cycle
Set your phone so the 0.96" window fills the frame, and turn off lights that reflect in the glass. Start recording, wait until the opening picture comes back, and stop after it arrives a second time. That's one honest pass of Khayalon Ki Duniya on your panel. A two-second clip from the middle can look like a frozen poster.
You won't hear the song in that take. Your OLED shows monochrome pictures only. If you edit the footage later, don't expect lip sync against a studio track. The stock loop is 8.3 seconds of bitmaps at ~15 fps, not a clock locked to the recording. If you re-export your own clip with dither on, you'll see speckle, and that's just data. It should look like fine pepper on gradients, not like a rolling bar down the panel. A rolling bar is a power or I2C problem.
Black panel, wrong chip, not enough flash
- Black screen: confirm 3.3V on your ESP's VCC, check GND continuity, and make sure SDA/SCL match the table. If you've swapped the data and clock lines, it looks exactly like a dead module.
- Wrong address: if Serial prints
SSD1306 allocation failed, edit the address from0x3Cto0x3Donce. Most of these 0.96" boards are 0x3C, but a few are strapped the other way. If you get no ACK on either address, the problem is your wires, not the song file. - Board menu: NodeMCU 1.0 is the usual ESP8266 entry you'll pick. An ESP32-S3 and a classic ESP32 Dev Module won't take each other's upload, so check which one you've got. If the port vanishes when you plug in, install the matching board package and the USB driver before you touch your OLED code.
- Flash: 124 KB of frames plus Adafruit libraries needs a real sketch region. On ESP8266 choose 4MB (1MB or more for the sketch, not a tiny 512KB profile). An Uno will always report that the sketch doesn't fit, and that message is accurate.
Questions that come up with this 124-frame file
Does the sketch print or speak the Hindi title for me?
Neither. Khayalon Ki Duniya is the name of the visual. main.ino doesn't scroll the title and doesn't play audio. You're uploading 124 monochrome frames, nothing else.
Why do I have to call the folder main?
Your sketch file is main.ino, and the IDE needs the containing folder to use that same name. Rename the unzipped GitHub folder to main, then open the file.
My loop takes longer than 8.3 seconds. Did my upload drop frames?
Usually the bus is slower than the 67 ms target. Time one cycle yourself. If it's closer to 12 seconds, display() is stretching each frame. Wire.setClock(400000) after begin, or a delay of 100 ms, makes the timing match the table. A missing frame looks like a jump. It doesn't look like a uniformly slow loop.
Can the Uno run it if I select a huge flash size?
No. The Uno has about 32 KB of flash and the menu can't add more. You'll need an ESP32 or a 4MB ESP8266 for 124 KB of bitmaps (a Mega is the AVR exception if you rewire I2C to pins 20 and 21).
Related posts
Free tools: OLED Animation Maker for your SSD1306 and SH1106 animations, Assemble Studio for your name and logo animations, the Shadow Box Lamp Generator for your 3D-printed shadow lamps, Text to STL for your 3D-printed names and keychains, and 3MF to Web to show your 3D prints on any website. New: the Image to Byte Array converter, the OLED Robot Eyes generator and the Lithophane Maker. See all tools.