{"id":28958386,"url":"https://github.com/geo-mena/pixii","last_synced_at":"2026-04-10T23:40:06.913Z","repository":{"id":300635529,"uuid":"1006686287","full_name":"geo-mena/pixii","owner":"geo-mena","description":"🎨 Convert images, video to ascii!","archived":false,"fork":false,"pushed_at":"2025-06-22T20:03:16.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-22T20:37:10.053Z","etag":null,"topics":["markdown","shell","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geo-mena.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T19:46:20.000Z","updated_at":"2025-06-22T20:05:51.000Z","dependencies_parsed_at":"2025-06-22T20:47:20.228Z","dependency_job_id":null,"html_url":"https://github.com/geo-mena/pixii","commit_stats":null,"previous_names":["geo-mena/pixii"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/geo-mena/pixii","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geo-mena%2Fpixii","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geo-mena%2Fpixii/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geo-mena%2Fpixii/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geo-mena%2Fpixii/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geo-mena","download_url":"https://codeload.github.com/geo-mena/pixii/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geo-mena%2Fpixii/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267428304,"owners_count":24085723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","shell","zig"],"created_at":"2025-06-23T23:00:50.864Z","updated_at":"2026-04-10T23:40:06.881Z","avatar_url":"https://github.com/geo-mena.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n    \u003csource srcset=\"./.github/icon-dark.svg\" media=\"(prefers-color-scheme: light)\"\u003e\n    \u003csource srcset=\"./.github/icon-light.svg\" media=\"(prefers-color-scheme: dark)\"\u003e\n    \u003cimg src=\"./.github/icon-dark.svg\" alt=\"pixii\" width=\"120\" height=\"120\"\u003e\n\u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003epixii - convert images \u0026 video to ASCII art\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cstrong\u003eA high-performance CLI engine built entirely in Zig.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/geo-mena/pixii\"\u003e\u003cimg src=\"https://img.shields.io/badge/build-passing-brightgreen\" alt=\"Build Status\"\u003e\u003c/a\u003e\n\u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/geo-mena/pixii\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey\" alt=\"Platform\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/geo-mena/pixii/releases/tag/v1.0.11\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-1.0.11-orange\" alt=\"Version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Architecture Overview\n\npixii is designed as a modular pipeline that decomposes media processing into four specialized internal libraries, each with a single well-defined responsibility:\n\n```mermaid\nflowchart TB\n    CLI[\"main.zig — CLI Dispatcher\"] -- image input --\u003e IMG[\"libpixiiimg — Image Pipeline\"]\n    CLI -- video input --\u003e AV[\"libpixiiav — Video Pipeline\"]\n    IMG --\u003e CORE[\"libpixii — Core Engine\"] \u0026 TERM[\"libpixiiterm — Terminal Renderer\"]\n    AV --\u003e CORE \u0026 TERM \u0026 FFMPEG[\"av — FFmpeg Bindings\"]\n    CORE --\u003e STB[\"stb — Image I/O\"] \u0026 BMP[\"bitmap — 8x8 Font Rasterization\"]\n```\n\n- **libpixii** serves as the computational core, implementing Difference-of-Gaussians edge detection, Floyd-Steinberg dithering, histogram-based auto-contrast, Gaussian blur, and the brightness-to-character mapping engine.\n- **libpixiiimg** orchestrates the image processing flow: loading via STB, scaling, ASCII generation, and output encoding to PNG or plain text.\n- **libpixiiav** manages video decoding and encoding through FFmpeg, employing a multithreaded producer-consumer architecture with a thread-safe circular frame buffer for real-time terminal streaming.\n- **libpixiiterm** handles ANSI escape sequences for true-color rendering, cursor management, and adaptive terminal sizing.\n\n---\n\n## Installation\n\n### Homebrew\n\n```bash\nbrew tap geo-mena/pixii\nbrew install pixii\n```\n\n### Build from Source\n\nRequires **Zig 0.14.0** and FFmpeg development libraries.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePlatform-specific dependencies\u003c/strong\u003e\u003c/summary\u003e\n\n**Linux:**\n```bash\nsudo apt-get install libavutil-dev libavformat-dev libavcodec-dev libswscale-dev libswresample-dev pkg-config\n```\n\n**macOS:**\n```bash\nbrew install ffmpeg pkgconf\n```\n\n**Windows:**\n```bash\nchoco install ffmpeg-shared\n```\n\n\u003c/details\u003e\n\n```bash\nzig build -Doptimize=ReleaseFast\n```\n\nThe compiled binary will be located at `./zig-out/bin/pixii`. For direct execution without a separate install step:\n\n```bash\nzig build run -Doptimize=ReleaseFast -- [options]\n```\n\n---\n\n## Usage\n\n```bash\npixii -i \u003cinput\u003e [options]\n```\n\nWhen the `-o` flag is omitted, pixii renders directly to the terminal. The output format is inferred from the file extension: `.txt` produces plain text, video extensions produce encoded video, and all other extensions produce a PNG image.\n\n### Core Options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-i, --input \u003cfile\u003e` | Input media file, accepts local paths and URLs | **Required** |\n| `-o, --output \u003cfile\u003e` | Output file path | Terminal stdout |\n| `-c, --color` | Enable true-color ASCII rendering | Disabled |\n| `-n, --invert_color` | Invert brightness-to-character mapping | Disabled |\n| `-s, --scale \u003cfloat\u003e` | Resize factor applied before conversion | `1.0` |\n| `-a, --auto_adjust` | Histogram-based auto brightness and contrast | Disabled |\n| `-b, --brightness_boost \u003cfloat\u003e` | Manual brightness multiplier | `1.0` |\n| `-e, --detect_edges` | Enable Difference-of-Gaussians edge detection | Disabled |\n| `--stretched` | Fit output to terminal dimensions | Disabled |\n\n### Character Set Configuration\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--symbols \u003cstr\u003e` | Preset character set: `ascii` or `block` | `ascii` |\n| `--ascii_chars \u003cstr\u003e` | Custom character mapping string | ` .:-=+*%@#` |\n| `--full_characters` | Use the complete 70-character spectrum | Disabled |\n| `--disable_sort` | Prevent automatic sorting of characters by visual density | Disabled |\n| `--block_size \u003cu8\u003e` | Processing block size in pixels | `8` |\n\n### Edge Detection \u0026 Dithering\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--sigma1 \u003cfloat\u003e` | First Gaussian sigma for DoG filter | `0.5` |\n| `--sigma2 \u003cfloat\u003e` | Second Gaussian sigma for DoG filter | `1.0` |\n| `--threshold_disabled` | Disable edge magnitude threshold | Enabled |\n| `-d, --dither floydstein` | Apply Floyd-Steinberg error diffusion | Disabled |\n\n### Video-Specific Options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--codec \u003cstr\u003e` | Encoder codec, e.g. `libx264`, `hevc_videotoolbox` | Auto-detected |\n| `--keep_audio` | Preserve audio stream from input | Disabled |\n| `-f, --frame_rate \u003cfloat\u003e` | Target output frame rate | Matches input |\n| `--fg \u003chex\u003e` | Foreground color override | `#d36a6f` |\n| `--bg \u003chex\u003e` | Background color override | `#15091b` |\n\n---\n\n## Examples\n\n### Image Processing\n\nGenerate a basic ASCII image:\n```bash\npixii -i input.jpg -o output.png\n```\n\nExport as plain text:\n```bash\npixii -i input.jpg -o output.txt\n```\n\nEnable color with edge detection and a custom scale factor:\n```bash\npixii -i input.jpeg -o output.png -s 4 -e -c\n```\n\nRender directly in the terminal with brightness adjustment:\n```bash\npixii -i input.png -e -c -b 1.5\n```\n\n### Video Processing\n\nEncode an ASCII video preserving audio:\n```bash\npixii -i video.mp4 -o ascii.mp4 --codec hevc_nvenc --keep_audio\n```\n\nStream to terminal, stretched to fit the window:\n```bash\npixii -i video.mp4 --stretched -c\n```\n\nPass custom FFmpeg encoder parameters via positional arguments:\n```bash\npixii -i video.mp4 -o ascii.mp4 -c --codec libx264 --keep_audio -- -preset fast -crf 20\n```\n\n---\n\n## Supported Formats\n\n**Image input:** BMP, GIF, JPEG, PNG, TIFF, WebP, ICO\n**Video input:** MP4, AVI, MOV, WebM, MPEG, OGG, 3GP, 3G2, MPEG-TS\n**Output:** PNG, TXT, MP4, and any format supported by the installed FFmpeg encoders\n\n---\n\n## Platform Compatibility\n\n| Platform | Architecture | Status |\n|----------|-------------|--------|\n| macOS | ARM64, x86_64 | Supported |\n| Linux | x86_64, ARM64 | Supported |\n| Windows | x86_64 | Build from source |\n\n---\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeo-mena%2Fpixii","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeo-mena%2Fpixii","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeo-mena%2Fpixii/lists"}