{"id":34075156,"url":"https://github.com/bitomule/koubou","last_synced_at":"2026-04-17T21:02:05.642Z","repository":{"id":311915227,"uuid":"1045565379","full_name":"bitomule/Koubou","owner":"bitomule","description":"Transform YAML into handcrafted App Store screenshots. Koubou is your professional workshop where every screenshot  is carefully crafted with artisan quality.","archived":false,"fork":false,"pushed_at":"2026-04-16T17:59:05.000Z","size":108861,"stargazers_count":156,"open_issues_count":2,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-16T19:35:53.521Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/bitomule.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-27T11:30:27.000Z","updated_at":"2026-04-16T17:59:09.000Z","dependencies_parsed_at":"2025-08-27T20:54:44.556Z","dependency_job_id":"757ece83-5ba9-4d21-9ce5-cc1895780be5","html_url":"https://github.com/bitomule/Koubou","commit_stats":null,"previous_names":["bitomule/koubou"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/bitomule/Koubou","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitomule%2FKoubou","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitomule%2FKoubou/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitomule%2FKoubou/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitomule%2FKoubou/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitomule","download_url":"https://codeload.github.com/bitomule/Koubou/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitomule%2FKoubou/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31945987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2025-12-14T09:05:11.613Z","updated_at":"2026-04-17T21:02:00.630Z","avatar_url":"https://github.com/bitomule.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 Koubou (工房) - The Artisan Workshop for App Store Screenshots\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://python.org/)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)]()\n[![PyPI Version](https://img.shields.io/pypi/v/koubou)](https://pypi.org/project/koubou/)\n\n**Koubou (工房) transforms YAML into handcrafted App Store screenshots with artisan quality.**\n\n工房 (koubou) means \"artisan's workshop\" in Japanese - where masters create their finest work. Every screenshot is carefully crafted with professional precision using device frames, rich backgrounds, and elegant typography.\n\n## ✨ Features\n\n- **🔄 Live Editing** - Real-time screenshot regeneration when config or assets change\n- **🌍 Multi-Language Localization** - Generate localized screenshots using familiar xcstrings format from Xcode\n- **🖼️ Localized Assets** - Automatic language-specific asset resolution with convention-based and explicit mapping\n- **🎨 100+ Device Frames** - iPhone 16 Pro, iPad Air M2, MacBook Pro, Apple Watch Ultra, and more\n- **🌈 Professional Backgrounds** - Linear, radial, conic gradients with precise color control\n- **✨ Rich Typography** - Advanced text overlays with stroke, alignment, wrapping, and custom fonts\n- **🌈 Gradient Typography** - Linear, radial, and conic gradients for text with custom color stops\n- **📱 YAML-First Configuration** - Elegant, declarative screenshot definitions\n- **🚀 Batch Processing** - Generate multiple screenshots efficiently from a single config\n- **🔧 Flexible API** - Both simple and advanced configuration options\n- **💎 Artisan Quality** - Pixel-perfect output ready for App Store submission\n\n## 📦 Installation\n\n### Package Managers (Recommended)\n\n**PyPI (All Platforms)**\n```bash\npip install koubou\n```\n\n**macOS/Linux - Homebrew**\n```bash\nbrew install bitomule/tap/koubou\n```\n\n**Python Developers**\n```bash\npip install koubou[dev]  # With development dependencies\n```\n\n### Manual Installation\n\n**Option 1: Install Script (Recommended)**\n```bash\ngit clone https://github.com/bitomule/koubou.git\ncd koubou\n./install.sh\n```\n\n**Option 2: From Source**\n```bash\ngit clone https://github.com/bitomule/koubou.git\ncd koubou\npip install .\n```\n\n### Verification\n\nVerify your installation:\n```bash\nkou --version\nkou --help\n```\n\n## 🚀 Quick Start\n\n```bash\n# Create a sample configuration\nkou --create-config my-screenshots.yaml\n\n# Generate screenshots\nkou generate my-screenshots.yaml\n\n# Live editing mode - regenerate automatically when files change\nkou live my-screenshots.yaml\n```\n\n## 🔄 Live Editing\n\nReal-time screenshot regeneration when your YAML configuration or assets change.\n\n```bash\n# Start live editing mode\nkou live my-screenshots.yaml\n\n# Adjust debounce delay (default: 0.5s)\nkou live my-screenshots.yaml --debounce 1.0\n\n# Enable verbose logging\nkou live my-screenshots.yaml --verbose\n```\n\n**How it works:**\n- Monitors YAML config and all referenced assets\n- Regenerates only affected screenshots\n- Debounces rapid changes to prevent excessive regeneration\n\n**Perfect for iterative design** - edit assets in design tools, update text, tweak positioning, and see results instantly.\n\n**Platform support:** macOS and Linux only (standard generation works on Windows)\n\n---\n\n## 🌍 Multi-Language Localization\n\nGenerate localized screenshots for international App Store submissions using xcstrings format from Xcode.\n\n```yaml\nproject:\n  name: \"My App Screenshots\"\n  output_dir: \"Screenshots/Generated\"\n  device: \"iPhone 15 Pro Portrait\"\n  output_size: \"iPhone6_9\"\n\nlocalization:\n  base_language: \"en\"\n  languages: [\"en\", \"es\", \"ja\", \"fr\", \"de\"]\n  xcstrings_path: \"Localizable.xcstrings\"  # Optional - auto-creates if missing\n\nscreenshots:\n  welcome_screen:\n    content:\n      - type: \"text\"\n        content: \"Welcome to Amazing App\"  # Text becomes localization key\n        position: [\"50%\", \"20%\"]\n        size: 48\n        color: \"#8E4EC6\"\n      - type: \"image\"\n        asset: \"screenshots/home.png\"\n        position: [\"50%\", \"60%\"]\n```\n\n**Output structure:**\n```\nScreenshots/Generated/\n├── en/iPhone_15_Pro_Portrait/welcome_screen.png\n├── es/iPhone_15_Pro_Portrait/welcome_screen.png\n├── ja/iPhone_15_Pro_Portrait/welcome_screen.png\n├── fr/iPhone_15_Pro_Portrait/welcome_screen.png\n└── de/iPhone_15_Pro_Portrait/welcome_screen.png\n```\n\n**Workflow:** Koubou extracts text content and creates/updates your xcstrings file. Edit translations in Xcode's xcstrings editor, then regenerate screenshots. Live mode watches both YAML config and xcstrings file for changes.\n\n**Key benefits:** Uses iOS-native xcstrings format, natural text as keys (no IDs), supports plurals and device variants, works seamlessly with live mode.\n\n---\n\n## 🖼️ Localized Assets\n\nAutomatically resolve language-specific images for multi-language screenshots. Perfect for RTL layouts, region-specific content, or tools like Maestro that generate per-locale screenshots.\n\n### Convention-Based (Recommended)\n\nOrganize assets in `{lang}/` subdirectories - Koubou resolves them automatically:\n\n```yaml\nlocalization:\n  base_language: \"en\"\n  languages: [\"en\", \"es\", \"ja\"]\n\nscreenshots:\n  hero_screen:\n    content:\n      - type: \"image\"\n        asset: \"screenshots/hero.png\"  # Auto-resolves to screenshots/{lang}/hero.png\n        position: [\"50%\", \"50%\"]\n```\n\n**Directory structure:**\n```\nscreenshots/\n├── en/hero.png\n├── es/hero.png\n├── ja/hero.png\n└── hero.png  # Fallback for missing languages\n```\n\n**Resolution order:** `{lang}/path` → `{base_lang}/path` → `direct_path`\n\n### Explicit Mapping\n\nFor non-standard structures or external tool outputs:\n\n```yaml\nscreenshots:\n  onboarding:\n    content:\n      - type: \"image\"\n        asset:\n          en: \"maestro/en_iphone/onboarding.png\"\n          es: \"maestro/es_iphone/onboarding.png\"\n          ja: \"maestro/ja_iphone/onboarding.png\"\n          default: \"screenshots/fallback.png\"  # Optional\n        position: [\"50%\", \"50%\"]\n```\n\nMix both approaches in the same screenshot as needed.\n\n---\n\n## 📱 App Store Screenshot Sizes\n\nKoubou provides predefined App Store screenshot sizes configured at the project level. All screenshots in a single YAML file use the same output size.\n\n### Using Named Sizes\n\nSpecify the output size once in your project configuration:\n\n```yaml\nproject:\n  name: \"My App Screenshots\"\n  output_dir: \"Screenshots/Generated\"\n  device: \"iPhone 15 Pro Portrait\"\n  output_size: \"iPhone6_9\"  # All screenshots will be 1320×2868\n\nscreenshots:\n  welcome_screen:\n    content:\n      - type: \"image\"\n        asset: \"screenshots/home.png\"\n```\n\n### Available Sizes\n\nView all available sizes with descriptions:\n\n```bash\nkou list-sizes\n```\n\n**Common Sizes:**\n- `iPhone6_9` - iPhone 16 Pro Max, 15 Pro Max (1320×2868)\n- `iPhone6_7` - iPhone 15/14/13/12 Pro Max, Plus (1290×2796)\n- `iPhone6_1` - iPhone 16/15/14/13 Pro (1179×2556)\n- `iPadPro12_9` - iPad Pro 12.9\" (2048×2732)\n- `iPadPro11` - iPad Pro 11\", iPad Air 11\" M2 (1668×2388)\n\n### Custom Sizes\n\nYou can still specify custom dimensions when needed:\n\n```yaml\nproject:\n  name: \"My App Screenshots\"\n  device: \"iPhone 15 Pro Portrait\"\n  output_size: [1200, 2600]  # Custom width × height\n```\n\n### Multiple Sizes\n\nTo generate screenshots for different sizes, create separate YAML files:\n- `iphone-6-9.yaml` - All iPhone 6.9\" screenshots\n- `iphone-6-7.yaml` - All iPhone 6.7\" screenshots\n- `ipad-pro.yaml` - All iPad Pro screenshots\n\n---\n\n## 🎨 Configuration\n\nCreate screenshots with YAML configuration:\n\n```yaml\nproject:\n  name: \"My Beautiful App\"\n  output_dir: \"Screenshots/Generated\"\n  device: \"iPhone 15 Pro Portrait\"\n  output_size: \"iPhone6_9\"  # iPhone 16 Pro Max, 15 Pro Max\n\ndefaults:\n  background:\n    type: linear\n    colors: [\"#E8F0FE\", \"#F8FBFF\"]\n    direction: 180\n\nscreenshots:\n  welcome_screen:\n    content:\n      - type: \"text\"\n        content: \"Beautiful App\"\n        position: [\"50%\", \"15%\"]\n        size: 48\n        color: \"#8E4EC6\"\n        weight: \"bold\"\n      - type: \"text\"\n        content: \"Transform your workflow today\"\n        position: [\"50%\", \"25%\"]\n        size: 24\n        color: \"#1A73E8\"\n      - type: \"image\"\n        asset: \"screenshots/home.png\"\n        position: [\"50%\", \"60%\"]\n        scale: 0.6\n        frame: true\n```\n\nSee the YAML API Reference below for all available options including gradients, strokes, and advanced positioning.\n\n## 🎯 Commands\n\n### Core Commands\n\n- `kou generate \u003cconfig.yaml\u003e` - Generate screenshots from configuration\n- `kou live \u003cconfig.yaml\u003e` - Live editing mode with real-time regeneration\n- `kou list-sizes` - List available App Store screenshot sizes\n- `kou --create-config \u003coutput.yaml\u003e` - Create a sample configuration file\n- `kou --version` - Show version information\n- `kou --help` - Show detailed help\n\n### Command Options\n\n#### Generate Command\n```bash\n# Override output directory\nkou generate config.yaml --output ./custom-screenshots\n\n# Use custom frame directory\nkou generate config.yaml --frames ./my-frames\n\n# Enable verbose logging\nkou generate config.yaml --verbose\n```\n\n#### Live Editing Command\n```bash\n# Start live editing with default settings\nkou live config.yaml\n\n# Adjust debounce delay (default: 0.5s)\nkou live config.yaml --debounce 1.0\n\n# Enable verbose logging to see file changes\nkou live config.yaml --verbose\n```\n\n#### Configuration Creation\n```bash\n# Create config with custom project name\nkou --create-config config.yaml --name \"My App Screenshots\"\n```\n\n#### Upload to App Store Connect\n\nFor uploading screenshots, we recommend [App Store Connect CLI](https://github.com/rudrankriyam/App-Store-Connect-CLI):\n\n```bash\nbrew install appstoreconnect-cli\nasc auth login\n\n# Upload per device type and language\nasc assets screenshots upload \\\n  --version-localization \"LOC_ID\" \\\n  --path \"./output/en/iPhone_16_Pro_.../\" \\\n  --device-type \"IPHONE_69\"\n```\n\nKoubou outputs screenshots organized by `{language}/{device}/`, mapping directly to individual `asc` upload calls.\n\n## 🎨 Device Frames\n\nKoubou includes 100+ professionally crafted device frames:\n\n### iPhone Frames\n- iPhone 16 Pro (Black, Desert, Natural, White Titanium)\n- iPhone 16 (Black, Pink, Teal, Ultramarine, White)\n- iPhone 15 Pro/Max (All titanium colors)\n- iPhone 14 Pro/Max, 12-13 series, and more\n\n### iPad Frames\n- iPad Air 11\"/13\" M2 (Blue, Purple, Space Gray, Stardust)\n- iPad Pro 11\"/13\" M4 (Silver, Space Gray)\n- iPad Pro 2018-2021, iPad mini, and classic models\n\n### Mac \u0026 Watch Frames\n- MacBook Pro 2021 (14\" \u0026 16\"), MacBook Air 2020/2022\n- iMac 24\" Silver, iMac 2021\n- Apple Watch Series 4/7, Watch Ultra\n\n## 📖 YAML API Reference\n\n### Project Configuration\n```yaml\nproject:\n  name: string               # Project name\n  output_dir: string         # Output directory (default: \"output\")\n  device: string             # Target device frame (default: \"iPhone 15 Pro Portrait\")\n  output_size: string | [int, int]  # Named size (\"iPhone6_9\") or custom [width, height] (default: \"iPhone6_9\")\n\ndefaults:                    # Default settings applied to all screenshots\n  background:                # Default background configuration\n    type: \"solid\" | \"linear\" | \"radial\" | \"conic\"\n    colors: [string, ...]    # Hex colors array\n    direction: float?        # Degrees for gradients (default: 0)\n```\n\n### Screenshot Configuration\n```yaml\nscreenshots:\n  screenshot_id:             # Unique identifier for each screenshot\n    content:                 # Array of content items\n      - type: \"text\" | \"image\"\n        # Text content properties\n        content: string?     # Text content (for type: \"text\")\n        position: [string, string]  # Position as [\"x%\", \"y%\"] or [\"xpx\", \"ypx\"]\n        size: int?           # Font size (default: 24)\n        color: string?       # Hex color (default: \"#000000\")\n        weight: string?      # \"normal\" or \"bold\" (default: \"normal\")\n        alignment: string?   # \"left\", \"center\", \"right\" (default: \"center\")\n        # Image content properties\n        asset: string | dict? # Image path (string) or localized mapping (dict)\n        scale: float?        # Scale factor (default: 1.0)\n        frame: bool?         # Apply device frame (default: false)\n```\n\n### Background Configuration\n```yaml\nbackground:\n  type: \"solid\" | \"linear\" | \"radial\" | \"conic\"\n  colors: [string, ...]      # Hex colors (e.g., [\"#667eea\", \"#764ba2\"])\n  direction: float?          # Degrees for linear gradients (default: 0)\n  center: [string, string]?  # Center point for radial/conic [\"x%\", \"y%\"]\n```\n\n### Content Items\n```yaml\n# Text Content Item\n- type: \"text\"\n  content: string            # Text to display\n  position: [string, string] # Position as [\"50%\", \"20%\"] or [\"100px\", \"50px\"]\n  size: int                  # Font size in pixels (default: 24)\n  \n  # Fill Options (choose exactly one):\n  color: string              # Solid color (hex format, e.g., \"#000000\")\n  # OR\n  gradient:                  # Text gradient\n    type: \"linear\" | \"radial\" | \"conic\"\n    colors: [string, ...]    # Hex colors array (minimum 2)\n    positions: [float, ...]? # Color stops 0.0-1.0 (optional)\n    direction: float?        # Angle in degrees (linear)\n    center: [string, string]? # Center point (radial/conic)\n    radius: string?          # Radius for radial (\"50%\", \"100px\")\n    start_angle: float?      # Starting angle (conic)\n  \n  weight: string             # \"normal\" or \"bold\" (default: \"normal\")\n  alignment: string          # \"left\", \"center\", \"right\" (default: \"center\")\n  \n  # Stroke Options (optional):\n  stroke_width: int?         # Stroke width in pixels\n  stroke_color: string?      # Solid stroke color (hex format)\n  # OR\n  stroke_gradient:           # Gradient stroke (same structure as gradient)\n\n# Image Content Item\n- type: \"image\"\n  asset: string              # Path to image file\n  position: [string, string] # Position as [\"50%\", \"60%\"] or [\"200px\", \"300px\"]\n  scale: float               # Scale factor (default: 1.0)\n  frame: bool                # Apply device frame around image (default: false)\n```\n\n## 🏗️ Architecture\n\nKoubou uses a clean, modular architecture:\n\n- **CLI Layer** (`koubou.cli`): Command-line interface with rich output\n- **Configuration** (`koubou.config`): Pydantic-based type-safe configuration\n- **Generation Engine** (`koubou.generator`): Core screenshot generation logic\n- **Renderers** (`koubou.renderers`): Specialized rendering for backgrounds, text, frames\n- **Device Frames** (`koubou.frames`): 100+ device frame assets and metadata\n\n## 🔧 Development\n\n### Setup Development Environment\n```bash\n# Clone the repository\ngit clone https://github.com/bitomule/koubou.git\ncd koubou\n\n# Install in development mode with all dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nblack src/ tests/\nisort src/ tests/ \nflake8 src/ tests/\nmypy src/\n```\n\n### Running Tests\n```bash\n# Run all tests with coverage\npytest -v --cov=src/koubou\n\n# Run specific test file\npytest tests/test_generator.py -v\n\n# Run with live output\npytest -s\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and linting (`pytest`, `black`, `isort`, `flake8`, `mypy`)\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## 📋 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete version history.\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🎯 Koubou Philosophy\n\nIn the spirit of Japanese craftsmanship, Koubou embodies:\n\n- **職人気質 (Shokunin-kishitsu)** - Artisan spirit and dedication to craft\n- **完璧 (Kanpeki)** - Pursuit of perfection in every detail  \n- **簡潔 (Kanketsu)** - Elegant simplicity in design and usage\n- **品質 (Hinshitsu)** - Uncompromising quality in output\n\nEvery screenshot generated by Koubou reflects these values - carefully crafted, pixel-perfect, and ready for the world's most demanding app stores.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitomule%2Fkoubou","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitomule%2Fkoubou","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitomule%2Fkoubou/lists"}