1 line
9.2 KiB
JSON
1 line
9.2 KiB
JSON
{"repo": "baminq/pixmith", "files": {"README.md": {"ca9d8ed130a70bd5a6d8ba81b5b26e56b629340a": {"t": 1785674440.8788898, "n": 8332, "h": "f82956b8af11f2f1", "c": "<div align=\"center\">\n <h1 style=\"font-size: 48px; margin-bottom: 0;\">⚒️ Pixmith</h1>\n <p><em>Forge pixel-art game assets with AI</em></p>\n</div>\n\n<p align=\"center\">\n <img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\">\n <img src=\"https://img.shields.io/badge/Python-3.13-blue.svg\" alt=\"Python\">\n <img src=\"https://img.shields.io/badge/Node.js-22-green.svg\" alt=\"Node.js\">\n <img src=\"https://img.shields.io/badge/Angular-20-red.svg\" alt=\"Angular\">\n <img src=\"https://img.shields.io/badge/FastAPI-0.116-009688.svg\" alt=\"FastAPI\">\n</p>\n\n<p align=\"center\">\n 🇬🇧 English · <a href=\"./README_vi.md\">🇻🇳 Tiếng Việt</a>\n</p>\n\n**Pixmith** is an AI-powered workshop for crafting pixel-art game assets — images, animations, sprite sheets, and chiptune music. Built with a FastAPI backend and Angular frontend, it connects to any **OpenAI-compatible** API (OpenAI, OpenRouter, Groq, SiliconFlow, and more).\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Architecture](#%EF%B8%8F-architecture)\n- [Prerequisites](#-prerequisites)\n- [Installation](#-installation)\n- [Configuration](#%EF%B8%8F-configuration)\n- [Usage](#-usage)\n- [Supported APIs](#-supported-apis)\n- [Project Structure](#-project-structure)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## ✨ Features\n\n- 🎨 **Image Generation** — Generate pixel-art assets from text prompts\n- 🎬 **Animation Generation** — Turn a first frame + prompt into short videos\n- ✂️ **Frame Splitting** — Extract frames from animations for use as 2D sprites\n- 🧩 **Sprite Sheet Export** — Merge frames into a single sprite atlas (PNG)\n- 🧹 **Background Removal** *(beta)* — Strip backgrounds via `rembg`\n- 🎵 **Music Generation** — Compose original BGM with optional chiptune variant\n- 💾 **Caching & History** — Persistent cache of generated assets with browseable history\n- ⚙️ **OpenAI-compatible** — Plug in any provider that speaks the OpenAI API\n- 🌐 **i18n** — UI available in English, Vietnamese, and Chinese\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐ HTTP ┌──────────────────┐\n│ Angular 20 UI │ ──────────────► │ FastAPI Server │\n└─────────────────┘ └────────┬─────────┘\n │\n ▼\n ┌──────────────────────┐\n │ OpenAI-compatible │\n │ API (any provider) │\n └──────────────────────┘\n```\n\n- **Backend** — FastAPI handles API routing, model calls, and media processing.\n- **Frontend** — Angular SPA; API keys and endpoints are configured in **Settings** (browser localStorage).\n- **Cache** — Local filesystem stores generated images, frames, and music.\n- **Logs** — Daily-rotated server logs (`logs/`).\n\n## 📋 Prerequisites\n\n- **Python** 3.13+\n- **Node.js** 22+\n- **Angular CLI** 20+\n- An API key from any OpenAI-compatible provider\n\n## 🚀 Installation\n\n### 1. Clone the repository\n\n```bash\ngit clone https://github.com/baminq/pixmith.git\ncd pixmith\n```\n\n### 2. Backend setup\n\n```bash\ncd projects/server\n\npython -m venv venv\nsource venv/bin/activate # Linux/macOS\nvenv\\Scripts\\activate # Windows\n\npip install -r requirements.txt\n\ncp .env.example .env\n# Optional: set server defaults in .env\n\npython app.py\n```\n\nServer starts on `http://0.0.0.0:8000`.\n\n### 3. Frontend setup\n\n```bash\ncd projects/ui\nnpm install\nnpm start\n```\n\nUI available at `http://localhost:4200`.\n\nOpen **Settings** in the UI and add your OpenAI-compatible base URL, API key, and model for image / music / video.\n\n## ⚙️ Configuration\n\n### UI Settings (primary)\n\nAPI credentials are stored in the browser (localStorage) and sent with each generation request. Configure separately for:\n\n| Slot | Purpose |\n|---|---|\n| **Image API** | Text-to-image generation |\n| **Music API** | Chat/completion-based music generation |\n| **Video API** | Image-to-video animation |\n\nEach slot needs: provider name, **Base URL**, **API key**, and **Model**.\n\n### Server `.env` (optional defaults)\n\nAll server configuration lives in `projects/server/.env`. See `.env.example`.\n\n| Variable | Default | Description |\n|---|---|---|\n| `HOST` | `0.0.0.0` | Bind address |\n| `PORT` | `8000` | Server port |\n| `LOG_LEVEL` | `INFO` | Logging level |\n| `ALLOWED_ORIGINS` | `http://localhost:4200` | Comma-separated CORS origins |\n| `CUSTOM_BASE_URL` | *(empty)* | Optional default OpenAI-compatible endpoint |\n| `CUSTOM_API_KEY` | *(empty)* | Optional default API key |\n| `CUSTOM_MODEL` | *(empty)* | Optional default model name |\n| `CACHE_MAX_AGE_DAYS` | `7` | Auto-cleanup threshold for cached files |\n\n> **Never commit `.env` with real keys.** Use `.env.example` as a template.\n\n## 📖 Usage\n\n### Image generation\n\n```bash\ncurl -X POST http://localhost:8000/generate/image \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"A pixel-art ninja in black gear, full-body front view, gray background\",\n \"model_type\": \"custom\",\n \"size\": \"1024*1024\",\n \"custom_base_url\": \"https://api.openai.com/v1\",\n \"custom_api_key\": \"sk-...\",\n \"custom_model\": \"dall-e-3\"\n }'\n```\n\n### Video generation\n\n```bash\ncurl -X POST http://localhost:8000/generate/video \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"The ninja performs a slashing attack\",\n \"base_image_url\": \"https://example.com/ninja.png\",\n \"model_type\": \"custom\",\n \"custom_base_url\": \"https://api.example.com/v1\",\n \"custom_api_key\": \"sk-...\",\n \"custom_model\": \"your-i2v-model\"\n }'\n```\n\n### Music generation\n\n```bash\ncurl -X POST http://localhost:8000/generate/music \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"Cheerful 8-bit chiptune for a side-scrolling platformer\",\n \"duration\": 30,\n \"genre\": \"chiptune\",\n \"model_type\": \"custom\",\n \"custom_base_url\": \"https://api.openai.com/v1\",\n \"custom_api_key\": \"sk-...\",\n \"custom_model\": \"gpt-4o\"\n }'\n```\n\nFull API docs available at `http://localhost:8000/docs` after starting the server.\n\n## 🤖 Supported APIs\n\nPixmith talks to any endpoint that implements the OpenAI-compatible surface used for the task:\n\n| Capability | Typical endpoint shape | Example models |\n|---|---|---|\n| Image generation | `POST /images/generations` | `dall-e-3`, provider-specific image models |\n| Video / animation | Provider image-to-video API (OpenAI-compatible adapter) | Provider-specific I2V models |\n| Music (chat-based) | `POST /chat/completions` | `gpt-4o`, `gpt-4o-mini`, other chat models |\n\nSet `model_type: \"custom\"` and pass `custom_base_url`, `custom_api_key`, and `custom_model` in the request body (the UI does this automatically from Settings).\n\nWorks with providers such as **OpenAI**, **OpenRouter**, **Groq**, **SiliconFlow**, and self-hosted gateways that expose an OpenAI-compatible API.\n\n## 📁 Project Structure\n\n```\npixmith/\n├── projects/\n│ ├── server/ # FastAPI backend\n│ │ ├── app.py # Application entrypoint\n│ │ ├── defs.py # Pydantic schemas + constants\n│ │ ├── routers/ # HTTP endpoints\n│ │ └── services/\n│ │ ├── gen_models/ # AI provider adapters\n│ │ │ └── custom/ # OpenAI-compatible client\n│ │ └── utils/ # Frame, image, music, path helpers\n│ └── ui/ # Angular 20 frontend\n│ └── src/app/\n│ ├── components/\n│ ├── services/\n│ └── interceptors/\n├── assets/ # Docs / intro screenshots\n├── cache/ # Generated assets (gitignored)\n├── logs/ # Server logs (gitignored)\n├── scripts/ # Utility scripts (e.g. logo generation)\n├── LICENSE # MIT\n└── README.md\n```\n\n## 🤝 Contributing\n\nContributions welcome. Please:\n\n1. Open an issue first to discuss significant changes.\n2. Fork → branch → PR. Keep PRs focused and small.\n3. Add tests for new logic.\n4. Run linters before pushing.\n\n## 📄 License\n\nReleased under the [MIT License](LICENSE).\n\nCopyright (c) 2026 [baminq](https://github.com/baminq)\n\n## 🙏 Acknowledgments\n\n- [FastAPI](https://fastapi.tiangolo.com/)\n- [Angular](https://angular.dev/)\n- [rembg](https://github.com/danielgatis/rembg)\n- [music21](https://web.mit.edu/music21/) / [symusic](https://github.com/Yikai-Liao/symusic)\n"}}}} |