{"id":31481332,"url":"https://github.com/pinkpixel-dev/pixelpop","last_synced_at":"2025-10-02T06:48:47.448Z","repository":{"id":315772984,"uuid":"1060777027","full_name":"pinkpixel-dev/pixelpop","owner":"pinkpixel-dev","description":"🖼️ Display and animate images, GIFs, and photo sequences directly in your terminal with ANSI color support. Smart terminal detection, multiple rendering strategies, and TypeScript-ready.","archived":false,"fork":false,"pushed_at":"2025-09-20T15:43:22.000Z","size":7699,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T17:37:32.784Z","etag":null,"topics":["animation","ansi","ascii-art","cli","command-line","console","cross-platform","developer-tools","gif","gif-player","image","image-viewer","iterm2","kitty","nodejs","terminal","terminal-graphics","typescript","visualization","wezterm"],"latest_commit_sha":null,"homepage":"https://pinkpixel.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pinkpixel-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-20T15:15:45.000Z","updated_at":"2025-09-20T15:43:08.000Z","dependencies_parsed_at":"2025-09-20T17:37:35.966Z","dependency_job_id":"5d52a375-b362-43a1-8eb8-4171f315de31","html_url":"https://github.com/pinkpixel-dev/pixelpop","commit_stats":null,"previous_names":["pinkpixel-dev/pixelpop"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pinkpixel-dev/pixelpop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fpixelpop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fpixelpop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fpixelpop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fpixelpop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinkpixel-dev","download_url":"https://codeload.github.com/pinkpixel-dev/pixelpop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fpixelpop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276531307,"owners_count":25658697,"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-09-23T02:00:09.130Z","response_time":73,"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":["animation","ansi","ascii-art","cli","command-line","console","cross-platform","developer-tools","gif","gif-player","image","image-viewer","iterm2","kitty","nodejs","terminal","terminal-graphics","typescript","visualization","wezterm"],"created_at":"2025-10-02T06:48:45.680Z","updated_at":"2025-10-02T06:48:47.442Z","avatar_url":"https://github.com/pinkpixel-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003ePixelpop 🍭\u003c/h1\u003e\n  \u003ch6\u003e🖼️ Display and animate images, GIFs, and photo sequences directly in your terminal with ANSI color support 🖥️\u003c/h6\u003e\n  \u003cimg src=\"pixelpop.png\" alt=\"Pixelpop Logo\" width=\"350\" /\u003e\n  \n  [![npm version](https://badge.fury.io/js/%40pinkpixel%2Fpixelpop.svg)](https://badge.fury.io/js/%40pinkpixel%2Fpixelpop) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9.2-blue)](https://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dm/@pinkpixel/pixelpop.svg)](https://www.npmjs.com/package/@pinkpixel/pixelpop) [![GitHub Stars](https://img.shields.io/github/stars/pinkpixel-dev/pixelpop.svg)](https://github.com/pinkpixel-dev/pixelpop)\n  \n\u003c/div\u003e\n\nPixelpop is a sophisticated terminal utility library that brings visual content to command-line applications. With intelligent terminal detection and multiple rendering strategies, it ensures your images look great across different terminal environments.\n\n## 🎬 Demos\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eStatic Image Display\u003c/h3\u003e\n  \u003cimg src=\"demos/image_demo.gif\" alt=\"Static Image Demo\" width=\"600\" /\u003e\n  \n  \u003ch3\u003eAnimated GIF Playback\u003c/h3\u003e\n  \u003cimg src=\"demos/gif_demo.gif\" alt=\"GIF Animation Demo\" width=\"600\" /\u003e\n\u003c/div\u003e\n\n## ✨ Features\n\n- 🖼️ **Multi-format Support** - Display JPEG, PNG, GIF, and more\n- 🎬 **GIF Animation** - Smooth animated GIF playback with frame rate control\n- 🎯 **Smart Terminal Detection** - Automatically adapts to your terminal's capabilities\n- 📐 **Flexible Sizing** - Percentage-based dimensions with aspect ratio preservation\n- 🌈 **Universal Compatibility** - Works in iTerm2, Kitty, WezTerm, and standard terminals\n- ⚡ **High Performance** - Optimized rendering with intelligent fallbacks\n- 🔧 **TypeScript Ready** - Full type definitions included\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Using npm\nnpm install @pinkpixel/pixelpop\n\n# Using yarn\nyarn add @pinkpixel/pixelpop\n\n# Using pnpm\npnpm add @pinkpixel/pixelpop\n```\n\nNote: `@pinkpixel/pixelpop` is ESM-only (`\"type\": \"module\"`). Use ESM in your project, or use dynamic `import()` from CommonJS if needed.\n\n### Basic Usage\n\n```typescript\nimport pixelPop from \"@pinkpixel/pixelpop\";\n\n// Display a static image\nconst output = await pixelPop.file(\"./my-image.jpg\", {\n  width: \"50%\",\n});\nconsole.log(output);\n\n// Play an animated GIF\nconst stop = await pixelPop.gifFile(\"./my-animation.gif\", {\n  width: \"80%\",\n  maximumFrameRate: 24,\n});\n\n// Stop the animation after 5 seconds\nsetTimeout(stop, 5000);\n```\n\n## 📖 API Reference\n\n### Static Image Methods\n\n#### `pixelPop.file(filePath, options?)`\n\nDisplay an image from a file path.\n\n```typescript\nawait pixelPop.file(\"./image.jpg\", {\n  width: \"60%\",\n  height: 20,\n  preserveAspectRatio: true,\n});\n```\n\n#### `pixelPop.buffer(buffer, options?)`\n\nDisplay an image from a buffer.\n\n```typescript\nconst imageBuffer = fs.readFileSync(\"./image.jpg\");\nawait pixelPop.buffer(imageBuffer, { width: \"50%\" });\n```\n\n### Animated GIF Methods\n\n#### `pixelPop.gifFile(filePath, options?)`\n\nPlay an animated GIF from a file path. Returns a function to stop the animation.\n\n```typescript\nconst stop = await pixelPop.gifFile(\"./animation.gif\", {\n  width: \"75%\",\n  maximumFrameRate: 30,\n});\n```\n\n#### `pixelPop.gifBuffer(buffer, options?)`\n\nPlay an animated GIF from a buffer. Returns a function to stop the animation.\n\n```typescript\nconst gifBuffer = fs.readFileSync(\"./animation.gif\");\nconst stop = await pixelPop.gifBuffer(gifBuffer, {\n  maximumFrameRate: 15,\n});\n```\n\n### Options\n\n#### `RenderOptions`\n\n```typescript\ninterface RenderOptions {\n  width?: DimensionValue; // number or percentage string like '50%'\n  height?: DimensionValue; // number or percentage string like '50%'\n  preserveAspectRatio?: boolean; // default: true\n}\n```\n\n#### `GifOptions`\n\n```typescript\ninterface GifOptions extends RenderOptions {\n  maximumFrameRate?: number; // default: 30\n  renderFrame?: RenderFrame; // custom frame renderer\n}\n```\n\n#### `DimensionValue`\n\n```typescript\ntype DimensionValue = number | `${number}%`;\n```\n\n## 🎯 Examples\n\n### Responsive Image Display\n\n```typescript\nimport pixelPop from \"@pinkpixel/pixelpop\";\n\n// Adapt to terminal size\nawait pixelPop.file(\"./hero-image.jpg\", {\n  width: \"100%\",\n  preserveAspectRatio: true,\n});\n```\n\n### Controlled GIF Animation\n\n```typescript\nimport pixelPop from \"@pinkpixel/pixelpop\";\n\nconst stop = await pixelPop.gifFile(\"./loading.gif\", {\n  width: \"25%\",\n  maximumFrameRate: 20,\n});\n\n// Stop after process completes\nawait someAsyncOperation();\nstop();\n```\n\n### Custom Frame Rendering\n\n```typescript\nimport pixelPop from \"@pinkpixel/pixelpop\";\nimport logUpdate from \"log-update\";\n\nconst customRenderer = (frame: string) =\u003e {\n  logUpdate(`\\n🎬 Animation Frame:\\n${frame}`);\n};\n\ncustomRenderer.done = () =\u003e {\n  logUpdate.done();\n  console.log(\"Animation complete!\");\n};\n\nawait pixelPop.gifFile(\"./demo.gif\", {\n  renderFrame: customRenderer,\n  maximumFrameRate: 24,\n});\n```\n\n### Buffer Processing\n\n```typescript\nimport pixelPop from \"@pinkpixel/pixelpop\";\nimport { promises as fs } from \"fs\";\n\nconst imageBuffer = await fs.readFile(\"./screenshot.png\");\nconst output = await pixelPop.buffer(imageBuffer, {\n  width: 80,\n  height: \"50%\",\n});\n\nconsole.log(output);\n```\n\n## 🏗️ How It Works\n\nPixelpop uses a sophisticated multi-strategy rendering approach:\n\n### 1. **Terminal Detection**\n\nAutomatically detects your terminal's capabilities by checking environment variables:\n\n- `TERM_PROGRAM` (iTerm2, WezTerm, etc.)\n- `TERM` (xterm-kitty, etc.)\n- `KITTY_WINDOW_ID` and `KONSOLE_VERSION`\n\n### 2. **Rendering Strategies**\n\n#### 🏆 **Native Support** (iTerm2, etc.)\n\nUses `term-img` for terminals with built-in image protocols.\n\n#### ⚡ **Kitty Protocol** (Kitty, WezTerm, Konsole)\n\nDirect image rendering using Kitty's graphics protocol for superior quality.\n\n#### 🌈 **ANSI Fallback** (Universal)\n\nBlock character rendering with RGB colors using Chalk - works everywhere!\n\n### 3. **GIF Processing**\n\n- FFmpeg-based frame extraction to temporary files\n- Controlled animation loop with configurable frame rates\n- Automatic cleanup of temporary resources\n\n## 🎨 Terminal Compatibility\n\n| Terminal         | Strategy       | Quality    |\n| ---------------- | -------------- | ---------- |\n| iTerm2           | Native         | ⭐⭐⭐⭐⭐ |\n| Kitty            | Kitty Protocol | ⭐⭐⭐⭐⭐ |\n| WezTerm          | Kitty Protocol | ⭐⭐⭐⭐⭐ |\n| Warp             | ANSI Fallback  | ⭐⭐⭐⭐   |\n| Konsole          | Kitty Protocol | ⭐⭐⭐⭐   |\n| Terminal.app     | ANSI Fallback  | ⭐⭐⭐     |\n| Windows Terminal | ANSI Fallback  | ⭐⭐⭐     |\n| Standard xterm   | ANSI Fallback  | ⭐⭐⭐     |\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js \u003e= 20\n- npm, yarn, or pnpm\n\n### Setup\n\n```bash\ngit clone https://github.com/pinkpixel-dev/pixelpop.git\ncd pixelpop\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build     # Compile TypeScript\nnpm run clean     # Clean dist directory\nnpm run prepare   # Full build (runs automatically on install)\n```\n\n### Code Quality\n\n```bash\nnpm run lint      # Run ESLint\nnpm run lint:fix  # Fix ESLint issues\nnpm run typecheck # TypeScript validation\n```\n\n### Examples\n\nExamples in `examples/` are TypeScript. Run them with a TS runner like `tsx` or `ts-node`, or copy snippets into your own app:\n\n```bash\nnpm run build\n\n# Using tsx (recommended)\nnpx tsx examples/example.ts          # Static image demo\nnpx tsx examples/example_gif.ts      # Animated GIF demo\n\n# Or using ts-node (if installed)\nnode --loader ts-node/esm examples/example.ts\nnode --loader ts-node/esm examples/example_gif.ts\n```\n\n## 📚 Documentation\n\nPixelpop includes comprehensive documentation with detailed guides, examples, and API references. Visit the [`/docs`](./docs) directory for complete documentation:\n\n- **[📖 Getting Started Guide](./docs/getting-started.md)** - Installation, basic usage, and core concepts\n- **[🎯 API Reference](./docs/api-reference.md)** - Complete method documentation, types, and interfaces\n- **[🎬 GIF Animation Guide](./docs/gif-animation.md)** - Advanced animation techniques and performance optimization\n- **[🎨 Terminal Compatibility](./docs/terminal-compatibility.md)** - Terminal-specific optimizations and troubleshooting\n- **[💡 Examples \u0026 Recipes](./docs/examples.md)** - Real-world usage patterns and integration examples\n\n### Quick API Overview\n\n```typescript\n// Static images\nawait pixelPop.file(filePath, options?)     // Display image from file\nawait pixelPop.buffer(buffer, options?)     // Display image from buffer\n\n// Animated GIFs\nconst stop = await pixelPop.gifFile(filePath, options?)   // Play GIF from file\nconst stop = await pixelPop.gifBuffer(buffer, options?)   // Play GIF from buffer\n\n// All methods support:\n// - width/height: number | '50%' (percentage or pixels)\n// - preserveAspectRatio: boolean (default: true)\n// - maximumFrameRate: number (GIFs only, default: 30)\n// - renderFrame: custom renderer function (GIFs only)\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run the test suite: `npm test`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## ✨ Created by Pink Pixel\n\n**Website**: [https://pinkpixel.dev](https://pinkpixel.dev)\n**Email**: admin@pinkpixel.dev\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\u003cstrong\u003eMade with ❤️ by Pink Pixel\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e⭐ Star this repo if you find it useful!\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Fpixelpop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinkpixel-dev%2Fpixelpop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Fpixelpop/lists"}