A Pocket-Sized Cinema for Your Terminal: The Complete Sakura Guide

Play JPG, GIF, and MP4 in a command-line window with only ~1,000 lines of C++.

Table of Contents

1. What Exactly Is Sakura?
2. What Can It Do?
3. Quick Install in 60 Seconds
4. First Run: From Zero to Moving Pictures
5. Choosing the Right Render Mode
6. FAQ: The Questions Everyone Asks
7. Five Practical Performance Tweaks
8. Developer Corner: Embedding Sakura in Your Own Code
9. Common Errors and How to Fix Them
10. What to Tackle Next

What Exactly Is Sakura?

In plain words, Sakura is a tiny yet powerful multimedia player that lives inside your terminal.
It uses the SIXEL graphics protocol to draw pixels directly in the command-line window and relies on ffplay to keep audio perfectly in sync.

What Can It Do?

• Still images: JPG, PNG, BMP
• Animated GIFs with correct frame timing
• Video files: MP4, AVI, MOV, MKV (auto-scaled to fit your terminal)
• Remote media: paste any URL and stream on the fly
• Auto-resize: keeps the original aspect ratio no matter how you stretch the window

Quick Install in 60 Seconds

Ubuntu/Debian users: the cpr library is not in the default repositories. Build it once and forget it:

git clone https://github.com/libcpr/cpr.git
cd cpr && mkdir build && cd build
cmake .. && make && sudo make install

Build Sakura from Source

git clone https://github.com/Sarthak2143/sakura.git
cd sakura && mkdir build && cd build
cmake .. && make -j$(nproc)

You will end up with a single executable called sakura. Run it with ./sakura.

First Run: From Zero to Moving Pictures

1. Open a terminal and type ./sakura
2. You will see a simple menu:

   Sakura Video Player with SIXEL
   1. Image
   2. GIF
   3. Video (URL)
   4. Video (File)
   Choose option (1-4):
   

3. Pick a number, paste a path or URL, and press Enter.

Try It Right Now (No Local Files Needed)

# Random online image
echo -e "1\nhttps://picsum.photos/800/600" | ./sakura

# Public GIF
echo -e "2\nhttps://media.giphy.com/media/3o7qE1YN7aBOFPRw8E/giphy.gif" | ./sakura

Choosing the Right Render Mode

Sakura offers four ways to draw pictures. Pick the one that best matches your terminal and taste.

Switching modes in code is one line: change the RenderMode enum before you call a render function. You will see an example in the Developer Corner.

FAQ: The Questions Everyone Asks

Q1: My screen stays black. What happened?
A: First confirm your terminal can speak SIXEL.
Run this test string:

echo -e '\ePq"1;1;100;100#0;2;0;0;0#1;2;100;100;0#1~~@@vv@@~~@@~~$#0~~@@~~@@~~@@vv$#1!14~\e\\'

If you see colored squares, you are good. Otherwise try xterm -ti vt340 or switch to wezterm/foot.

Q2: Video stutters.
A: Three-step checklist

1. Press Ctrl+C and read the final line Drop Rate: x%. Anything below 10 % is fine.
2. Re-encode at a lower resolution: ffmpeg -i input.mp4 -vf scale=640:480 smaller.mp4
3. In RenderOptions, reduce scale_factor to 0.5.

Q3: I have picture but no sound.
A: Make sure ffplay is on your PATH and your volume is up:

which ffplay
ffplay -nodisp -autoexit test.mp4

Q4: Can I play YouTube links directly?
A: Not today. First download the file with yt-dlp or youtube-dl, then open the local copy with Sakura.

Q5: How do I quit?
A: Press q or hit Ctrl+C.

Five Practical Performance Tweaks

1. Pre-scale heavy videos
   ffmpeg -i big.mp4 -vf scale=1280:720 -r 30 lite.mp4
2. Lower the color palette
   In RenderOptions, set paletteSize to 128 or even 64.
3. Enable hardware acceleration
   When FFmpeg is compiled with --enable-nvenc, Sakura benefits automatically.
4. Close desktop effects
   On older laptops, turning off the compositor frees CPU cycles.
5. Use a lightweight terminal
   foot and alacritty impose less overhead than full desktop terminals.

Developer Corner: Embedding Sakura in Your Own Code

Minimal Working Example

#include "sakura.hpp"

int main() {
    Sakura player;
    RenderOptions opt;
    opt.mode = SIXEL;
    opt.paletteSize = 256;

    // 1. Display an online image
    player.renderFromUrl("https://example.com/pic.jpg", opt);

    // 2. Play a local video with audio
    player.renderVideoFromFile("clip.mp4", opt);

    return 0;
}

Key Classes Quick Reference

Batch Processing Loop

std::vector<std::string> urls = { "a.jpg", "b.jpg", "c.jpg" };
for (const auto& u : urls) {
    player.renderFromUrl(u, opt);
    std::this_thread::sleep_for(std::chrono::seconds(2)); // pause 2 s
}

NixOS Users

If you are on NixOS, Flakes make life easy.

# configuration.nix
{
  inputs.sakura.url = "github:sarthak2143/sakura";
  inputs.sakura.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { self, nixpkgs, sakura }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        sakura.nixosModules.sakura
      ];
    };
  };
}
# enable the package
programs.sakura.enable = true;

Try it once without installing:

nix run github:sarthak2143/sakura

Common Errors and How to Fix Them

What to Tackle Next

The project’s TODO list is short and public:

• Cut frame-drops to ≤ 5 %.
• Add custom exception classes for clearer error messages.

You could also:

• Stream an IP-camera RTSP feed into Sakura after lightweight transcoding.
• Turn a Raspberry Pi into a “terminal photo frame” that cycles through family pictures.

Closing Thoughts

Sakura is not about flashy demos; it is about enough power in a tiny footprint.
One thousand lines of C++ give you a cinema in your terminal—useful for education, embedded work, and remote debugging alike.
If you build something fun with it, open an issue or pull request on GitHub and share the joy.