Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bitomule/koubou

Transform YAML into handcrafted App Store screenshots. Koubou is your professional workshop where every screenshot is carefully crafted with artisan quality.
https://github.com/bitomule/koubou

Last synced: 2 months ago
JSON representation

Transform YAML into handcrafted App Store screenshots. Koubou is your professional workshop where every screenshot is carefully crafted with artisan quality.

Awesome Lists containing this project

README 

          
# ๐ŸŽฏ Koubou (ๅทฅๆˆฟ) - The Artisan Workshop for App Store Screenshots



[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://python.org/)

[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)]()

[![PyPI Version](https://img.shields.io/pypi/v/koubou)](https://pypi.org/project/koubou/)



**Koubou (ๅทฅๆˆฟ) transforms YAML into handcrafted App Store screenshots with artisan quality.**



ๅทฅๆˆฟ (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.



## โœจ Features



- **๐Ÿ”„ Live Editing** - Real-time screenshot regeneration when config or assets change

- **๐ŸŒ Multi-Language Localization** - Generate localized screenshots using familiar xcstrings format from Xcode

- **๐Ÿ–ผ๏ธ Localized Assets** - Automatic language-specific asset resolution with convention-based and explicit mapping

- **๐ŸŽจ 100+ Device Frames** - iPhone 16 Pro, iPad Air M2, MacBook Pro, Apple Watch Ultra, and more

- **๐ŸŒˆ Professional Backgrounds** - Linear, radial, conic gradients with precise color control

- **โœจ Rich Typography** - Advanced text overlays with stroke, alignment, wrapping, and custom fonts

- **๐ŸŒˆ Gradient Typography** - Linear, radial, and conic gradients for text with custom color stops

- **๐Ÿ“ฑ YAML-First Configuration** - Elegant, declarative screenshot definitions

- **๐Ÿš€ Batch Processing** - Generate multiple screenshots efficiently from a single config

- **๐Ÿ”ง Flexible API** - Both simple and advanced configuration options

- **๐Ÿ’Ž Artisan Quality** - Pixel-perfect output ready for App Store submission



## ๐Ÿ“ฆ Installation



### Package Managers (Recommended)



**PyPI (All Platforms)**

```bash

pip install koubou

```



**macOS/Linux - Homebrew**

```bash

brew install bitomule/tap/koubou

```



**Python Developers**

```bash

pip install koubou[dev]  # With development dependencies

```



### Manual Installation



**Option 1: Install Script (Recommended)**

```bash

git clone https://github.com/bitomule/koubou.git

cd koubou

./install.sh

```



**Option 2: From Source**

```bash

git clone https://github.com/bitomule/koubou.git

cd koubou

pip install .

```



### Verification



Verify your installation:

```bash

kou --version

kou --help

```



## ๐Ÿš€ Quick Start



```bash

# Create a sample configuration

kou --create-config my-screenshots.yaml



# Generate screenshots

kou generate my-screenshots.yaml



# Live editing mode - regenerate automatically when files change

kou live my-screenshots.yaml

```



## ๐Ÿ”„ Live Editing



Real-time screenshot regeneration when your YAML configuration or assets change.



```bash

# Start live editing mode

kou live my-screenshots.yaml



# Adjust debounce delay (default: 0.5s)

kou live my-screenshots.yaml --debounce 1.0



# Enable verbose logging

kou live my-screenshots.yaml --verbose

```



**How it works:**

- Monitors YAML config and all referenced assets

- Regenerates only affected screenshots

- Debounces rapid changes to prevent excessive regeneration



**Perfect for iterative design** - edit assets in design tools, update text, tweak positioning, and see results instantly.



**Platform support:** macOS and Linux only (standard generation works on Windows)



---



## ๐ŸŒ Multi-Language Localization



Generate localized screenshots for international App Store submissions using xcstrings format from Xcode.



```yaml

project:

  name: "My App Screenshots"

  output_dir: "Screenshots/Generated"

  device: "iPhone 15 Pro Portrait"

  output_size: "iPhone6_9"



localization:

  base_language: "en"

  languages: ["en", "es", "ja", "fr", "de"]

  xcstrings_path: "Localizable.xcstrings"  # Optional - auto-creates if missing



screenshots:

  welcome_screen:

    content:

      - type: "text"

        content: "Welcome to Amazing App"  # Text becomes localization key

        position: ["50%", "20%"]

        size: 48

        color: "#8E4EC6"

      - type: "image"

        asset: "screenshots/home.png"

        position: ["50%", "60%"]

```



**Output structure:**

```

Screenshots/Generated/

โ”œโ”€โ”€ en/iPhone_15_Pro_Portrait/welcome_screen.png

โ”œโ”€โ”€ es/iPhone_15_Pro_Portrait/welcome_screen.png

โ”œโ”€โ”€ ja/iPhone_15_Pro_Portrait/welcome_screen.png

โ”œโ”€โ”€ fr/iPhone_15_Pro_Portrait/welcome_screen.png

โ””โ”€โ”€ de/iPhone_15_Pro_Portrait/welcome_screen.png

```



**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.



**Key benefits:** Uses iOS-native xcstrings format, natural text as keys (no IDs), supports plurals and device variants, works seamlessly with live mode.



---



## ๐Ÿ–ผ๏ธ Localized Assets



Automatically resolve language-specific images for multi-language screenshots. Perfect for RTL layouts, region-specific content, or tools like Maestro that generate per-locale screenshots.



### Convention-Based (Recommended)



Organize assets in `{lang}/` subdirectories - Koubou resolves them automatically:



```yaml

localization:

  base_language: "en"

  languages: ["en", "es", "ja"]



screenshots:

  hero_screen:

    content:

      - type: "image"

        asset: "screenshots/hero.png"  # Auto-resolves to screenshots/{lang}/hero.png

        position: ["50%", "50%"]

```



**Directory structure:**

```

screenshots/

โ”œโ”€โ”€ en/hero.png

โ”œโ”€โ”€ es/hero.png

โ”œโ”€โ”€ ja/hero.png

โ””โ”€โ”€ hero.png  # Fallback for missing languages

```



**Resolution order:** `{lang}/path` โ†’ `{base_lang}/path` โ†’ `direct_path`



### Explicit Mapping



For non-standard structures or external tool outputs:



```yaml

screenshots:

  onboarding:

    content:

      - type: "image"

        asset:

          en: "maestro/en_iphone/onboarding.png"

          es: "maestro/es_iphone/onboarding.png"

          ja: "maestro/ja_iphone/onboarding.png"

          default: "screenshots/fallback.png"  # Optional

        position: ["50%", "50%"]

```



Mix both approaches in the same screenshot as needed.



---



## ๐Ÿ“ฑ App Store Screenshot Sizes



Koubou provides predefined App Store screenshot sizes configured at the project level. All screenshots in a single YAML file use the same output size.



### Using Named Sizes



Specify the output size once in your project configuration:



```yaml

project:

  name: "My App Screenshots"

  output_dir: "Screenshots/Generated"

  device: "iPhone 15 Pro Portrait"

  output_size: "iPhone6_9"  # All screenshots will be 1320ร—2868



screenshots:

  welcome_screen:

    content:

      - type: "image"

        asset: "screenshots/home.png"

```



### Available Sizes



View all available sizes with descriptions:



```bash

kou list-sizes

```



**Common Sizes:**

- `iPhone6_9` - iPhone 16 Pro Max, 15 Pro Max (1320ร—2868)

- `iPhone6_7` - iPhone 15/14/13/12 Pro Max, Plus (1290ร—2796)

- `iPhone6_1` - iPhone 16/15/14/13 Pro (1179ร—2556)

- `iPadPro12_9` - iPad Pro 12.9" (2048ร—2732)

- `iPadPro11` - iPad Pro 11", iPad Air 11" M2 (1668ร—2388)



### Custom Sizes



You can still specify custom dimensions when needed:



```yaml

project:

  name: "My App Screenshots"

  device: "iPhone 15 Pro Portrait"

  output_size: [1200, 2600]  # Custom width ร— height

```



### Multiple Sizes



To generate screenshots for different sizes, create separate YAML files:

- `iphone-6-9.yaml` - All iPhone 6.9" screenshots

- `iphone-6-7.yaml` - All iPhone 6.7" screenshots

- `ipad-pro.yaml` - All iPad Pro screenshots



---



## ๐ŸŽจ Configuration



Create screenshots with YAML configuration:



```yaml

project:

  name: "My Beautiful App"

  output_dir: "Screenshots/Generated"

  device: "iPhone 15 Pro Portrait"

  output_size: "iPhone6_9"  # iPhone 16 Pro Max, 15 Pro Max



defaults:

  background:

    type: linear

    colors: ["#E8F0FE", "#F8FBFF"]

    direction: 180



screenshots:

  welcome_screen:

    content:

      - type: "text"

        content: "Beautiful App"

        position: ["50%", "15%"]

        size: 48

        color: "#8E4EC6"

        weight: "bold"

      - type: "text"

        content: "Transform your workflow today"

        position: ["50%", "25%"]

        size: 24

        color: "#1A73E8"

      - type: "image"

        asset: "screenshots/home.png"

        position: ["50%", "60%"]

        scale: 0.6

        frame: true

```



See the YAML API Reference below for all available options including gradients, strokes, and advanced positioning.



## ๐ŸŽฏ Commands



### Core Commands



- `kou generate ` - Generate screenshots from configuration

- `kou live ` - Live editing mode with real-time regeneration

- `kou list-sizes` - List available App Store screenshot sizes

- `kou --create-config ` - Create a sample configuration file

- `kou --version` - Show version information

- `kou --help` - Show detailed help



### Command Options



#### Generate Command

```bash

# Override output directory

kou generate config.yaml --output ./custom-screenshots



# Use custom frame directory

kou generate config.yaml --frames ./my-frames



# Enable verbose logging

kou generate config.yaml --verbose

```



#### Live Editing Command

```bash

# Start live editing with default settings

kou live config.yaml



# Adjust debounce delay (default: 0.5s)

kou live config.yaml --debounce 1.0



# Enable verbose logging to see file changes

kou live config.yaml --verbose

```



#### Configuration Creation

```bash

# Create config with custom project name

kou --create-config config.yaml --name "My App Screenshots"

```



#### Upload to App Store Connect



For uploading screenshots, we recommend [App Store Connect CLI](https://github.com/rudrankriyam/App-Store-Connect-CLI):



```bash

brew install appstoreconnect-cli

asc auth login



# Upload per device type and language

asc assets screenshots upload \

  --version-localization "LOC_ID" \

  --path "./output/en/iPhone_16_Pro_.../" \

  --device-type "IPHONE_69"

```



Koubou outputs screenshots organized by `{language}/{device}/`, mapping directly to individual `asc` upload calls.



## ๐ŸŽจ Device Frames



Koubou includes 100+ professionally crafted device frames:



### iPhone Frames

- iPhone 16 Pro (Black, Desert, Natural, White Titanium)

- iPhone 16 (Black, Pink, Teal, Ultramarine, White)

- iPhone 15 Pro/Max (All titanium colors)

- iPhone 14 Pro/Max, 12-13 series, and more



### iPad Frames

- iPad Air 11"/13" M2 (Blue, Purple, Space Gray, Stardust)

- iPad Pro 11"/13" M4 (Silver, Space Gray)

- iPad Pro 2018-2021, iPad mini, and classic models



### Mac & Watch Frames

- MacBook Pro 2021 (14" & 16"), MacBook Air 2020/2022

- iMac 24" Silver, iMac 2021

- Apple Watch Series 4/7, Watch Ultra



## ๐Ÿ“– YAML API Reference



### Project Configuration

```yaml

project:

  name: string               # Project name

  output_dir: string         # Output directory (default: "output")

  device: string             # Target device frame (default: "iPhone 15 Pro Portrait")

  output_size: string | [int, int]  # Named size ("iPhone6_9") or custom [width, height] (default: "iPhone6_9")



defaults:                    # Default settings applied to all screenshots

  background:                # Default background configuration

    type: "solid" | "linear" | "radial" | "conic"

    colors: [string, ...]    # Hex colors array

    direction: float?        # Degrees for gradients (default: 0)

```



### Screenshot Configuration

```yaml

screenshots:

  screenshot_id:             # Unique identifier for each screenshot

    content:                 # Array of content items

      - type: "text" | "image"

        # Text content properties

        content: string?     # Text content (for type: "text")

        position: [string, string]  # Position as ["x%", "y%"] or ["xpx", "ypx"]

        size: int?           # Font size (default: 24)

        color: string?       # Hex color (default: "#000000")

        weight: string?      # "normal" or "bold" (default: "normal")

        alignment: string?   # "left", "center", "right" (default: "center")

        # Image content properties

        asset: string | dict? # Image path (string) or localized mapping (dict)

        scale: float?        # Scale factor (default: 1.0)

        frame: bool?         # Apply device frame (default: false)

```



### Background Configuration

```yaml

background:

  type: "solid" | "linear" | "radial" | "conic"

  colors: [string, ...]      # Hex colors (e.g., ["#667eea", "#764ba2"])

  direction: float?          # Degrees for linear gradients (default: 0)

  center: [string, string]?  # Center point for radial/conic ["x%", "y%"]

```



### Content Items

```yaml

# Text Content Item

- type: "text"

  content: string            # Text to display

  position: [string, string] # Position as ["50%", "20%"] or ["100px", "50px"]

  size: int                  # Font size in pixels (default: 24)

  

  # Fill Options (choose exactly one):

  color: string              # Solid color (hex format, e.g., "#000000")

  # OR

  gradient:                  # Text gradient

    type: "linear" | "radial" | "conic"

    colors: [string, ...]    # Hex colors array (minimum 2)

    positions: [float, ...]? # Color stops 0.0-1.0 (optional)

    direction: float?        # Angle in degrees (linear)

    center: [string, string]? # Center point (radial/conic)

    radius: string?          # Radius for radial ("50%", "100px")

    start_angle: float?      # Starting angle (conic)

  

  weight: string             # "normal" or "bold" (default: "normal")

  alignment: string          # "left", "center", "right" (default: "center")

  

  # Stroke Options (optional):

  stroke_width: int?         # Stroke width in pixels

  stroke_color: string?      # Solid stroke color (hex format)

  # OR

  stroke_gradient:           # Gradient stroke (same structure as gradient)



# Image Content Item

- type: "image"

  asset: string              # Path to image file

  position: [string, string] # Position as ["50%", "60%"] or ["200px", "300px"]

  scale: float               # Scale factor (default: 1.0)

  frame: bool                # Apply device frame around image (default: false)

```



## ๐Ÿ—๏ธ Architecture



Koubou uses a clean, modular architecture:



- **CLI Layer** (`koubou.cli`): Command-line interface with rich output

- **Configuration** (`koubou.config`): Pydantic-based type-safe configuration

- **Generation Engine** (`koubou.generator`): Core screenshot generation logic

- **Renderers** (`koubou.renderers`): Specialized rendering for backgrounds, text, frames

- **Device Frames** (`koubou.frames`): 100+ device frame assets and metadata



## ๐Ÿ”ง Development



### Setup Development Environment

```bash

# Clone the repository

git clone https://github.com/bitomule/koubou.git

cd koubou



# Install in development mode with all dependencies

pip install -e ".[dev]"



# Run tests

pytest



# Run linting

black src/ tests/

isort src/ tests/ 

flake8 src/ tests/

mypy src/

```



### Running Tests

```bash

# Run all tests with coverage

pytest -v --cov=src/koubou



# Run specific test file

pytest tests/test_generator.py -v



# Run with live output

pytest -s

```



## ๐Ÿค Contributing



Contributions are welcome! Please feel free to submit a Pull Request.



1. Fork the repository

2. Create a feature branch (`git checkout -b feature/amazing-feature`)

3. Make your changes

4. Run tests and linting (`pytest`, `black`, `isort`, `flake8`, `mypy`)

5. Commit your changes (`git commit -m 'Add amazing feature'`)

6. Push to the branch (`git push origin feature/amazing-feature`)

7. Open a Pull Request



## ๐Ÿ“‹ Changelog



See [CHANGELOG.md](CHANGELOG.md) for complete version history.



## ๐Ÿ“„ License



MIT License - see [LICENSE](LICENSE) for details.



## ๐ŸŽฏ Koubou Philosophy



In the spirit of Japanese craftsmanship, Koubou embodies:



- **่ทไบบๆฐ—่ณช (Shokunin-kishitsu)** - Artisan spirit and dedication to craft

- **ๅฎŒ็’ง (Kanpeki)** - Pursuit of perfection in every detail  

- **็ฐกๆฝ” (Kanketsu)** - Elegant simplicity in design and usage

- **ๅ“่ณช (Hinshitsu)** - Uncompromising quality in output



Every screenshot generated by Koubou reflects these values - carefully crafted, pixel-perfect, and ready for the world's most demanding app stores.