| Name | koubou JSON |
| Version |
0.6.0
JSON |
| download |
| home_page | None |
| Summary | ๐ฏ Koubou (ๅทฅๆฟ) - The artisan workshop for App Store screenshots |
| upload_time | 2025-09-02 22:24:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2025 David Collado
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
screenshot
app-store
graphics
automation
artisan
koubou
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ๐ฏ Koubou (ๅทฅๆฟ) - The Artisan Workshop for App Store Screenshots
[](LICENSE)
[](https://python.org/)
[]()
[](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
- **๐จ 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
**New in v0.5.0:** Koubou now supports real-time screenshot generation! The `live` command automatically regenerates screenshots when your YAML configuration or referenced assets change.
```bash
# Start live editing mode
kou live my-screenshots.yaml
# Optional: Adjust debounce delay (default: 0.5s)
kou live my-screenshots.yaml --debounce 1.0
# Enable verbose logging to see what's happening
kou live my-screenshots.yaml --verbose
```
### How Live Editing Works
1. **Smart Change Detection**: Monitors your YAML config file and all referenced assets
2. **Selective Regeneration**: Only regenerates screenshots affected by changes
3. **Dependency Tracking**: Automatically detects which assets each screenshot uses
4. **Debounced Updates**: Prevents excessive regeneration during rapid edits
### Live Editing Workflow
```yaml
# my-app-screenshots.yaml
project:
name: "My App"
output_dir: "Screenshots/Generated"
screenshots:
welcome_screen:
content:
- type: "image"
asset: "app-screens/welcome.png" # Live editing watches this file
frame: true
- type: "text"
content: "Welcome to the future" # Changes to this regenerate instantly
```
**Perfect for iterative design workflows** - edit your assets in design tools, update text content, or tweak positioning, and see results instantly without manual regeneration!
### Platform Support
- **Live Editing**: macOS and Linux only
- **Standard Generation**: macOS, Linux, and Windows
---
## ๐ Multi-Language Localization
Generate beautiful localized screenshots for international App Store submissions using the familiar xcstrings format from Xcode.
### Quick Setup
Add a localization block to your YAML configuration:
```yaml
project:
name: "My App Screenshots"
output_dir: "Screenshots/Generated"
# Enable multi-language support
localization:
base_language: "en"
languages: ["en", "es", "ja", "fr", "de"]
xcstrings_path: "Localizable.xcstrings" # optional
screenshots:
welcome_screen:
content:
- type: "text"
content: "Welcome to Amazing App" # This becomes a localization key
position: ["50%", "20%"]
size: 48
color: "#8E4EC6"
- type: "image"
asset: "screenshots/home.png"
position: ["50%", "60%"]
```
### How It Works
1. **Extract Text**: Koubou automatically finds all text content in your screenshots
2. **Generate xcstrings**: Creates or updates your xcstrings file with text as localization keys
3. **iOS-Familiar Format**: Edit translations in Xcode using the xcstrings editor you already know
4. **Auto-Generate Screenshots**: Run `kou generate config.yaml` to create screenshots for all languages
### 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
```
### Live Editing with Localization
Live mode works seamlessly with localization:
```bash
kou live config.yaml # Watches YAML config AND xcstrings file
```
- **Edit xcstrings in Xcode** โ All language screenshots regenerate automatically
- **Update YAML config** โ xcstrings file updates with new text keys
- **Change assets** โ All localized versions update
### Key Benefits
- **๐ iOS Developer Friendly**: Uses xcstrings format you already know from Xcode
- **๐ Natural Keys**: Your actual text becomes the localization key (no artificial IDs)
- **๐ Complete Localization**: Supports all xcstrings features including plurals and device variants
- **๐ Zero Extra Work**: Add localization block and run the same commands
- **๐ Live Updates**: Edit translations and see all screenshots update instantly
---
## ๐จ Configuration
Create elegant screenshots with YAML configuration:
```yaml
project:
name: "My Beautiful App"
output_dir: "Screenshots/Generated"
devices:
- "iPhone 15 Pro Portrait"
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
```
### Advanced Configuration
```yaml
project:
name: "Feature Showcase"
output_dir: "Screenshots/Generated"
devices:
- "iPhone 15 Pro Portrait"
defaults:
background:
type: radial
colors: ["#ff9a9e", "#fecfef", "#feca57"]
screenshots:
ai_analysis:
content:
- type: "text"
content: "โจ AI-Powered Analysis"
position: ["50%", "10%"]
size: 42
color: "#2c2c54"
weight: "bold"
- type: "text"
content: "Smart insights at your fingertips"
position: ["50%", "20%"]
size: 28
color: "#1A73E8"
- type: "image"
asset: "screenshots/analysis.png"
position: ["50%", "65%"]
scale: 0.5
frame: true
```
### Gradient Text Configuration
```yaml
screenshots:
gradient_showcase:
content:
- type: "text"
content: "๐ Gradient Magic"
position: ["50%", "15%"]
size: 48
gradient:
type: linear
colors: ["#FF6B6B", "#4ECDC4", "#45B7D1"]
direction: 45
weight: "bold"
- type: "text"
content: "Beautiful gradients for stunning text"
position: ["50%", "25%"]
size: 24
gradient:
type: radial
colors: ["#667eea", "#764ba2"]
center: ["50%", "50%"]
radius: "70%"
- type: "text"
content: "Advanced Color Control"
position: ["50%", "35%"]
size: 28
gradient:
type: linear
colors: ["#f093fb", "#f5576c", "#4facfe"]
positions: [0.0, 0.3, 1.0]
direction: 90
stroke_width: 2
stroke_gradient:
type: linear
colors: ["#333333", "#666666"]
direction: 45
```
## ๐ฏ Commands
### Core Commands
- `kou generate <config.yaml>` - Generate screenshots from configuration
- `kou live <config.yaml>` - **[New]** Live editing mode with real-time regeneration
- `kou --create-config <output.yaml>` - 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"
```
## ๐จ 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")
devices: [string, ...] # Target device list (e.g., ["iPhone 15 Pro Portrait"])
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: # Screenshots are now organized by ID (breaking change in v0.5.0)
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? # Image file path (for type: "image")
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
### v0.5.6 (Latest)
- โ
**Fixed**: All device frame PNG files now properly included in production installations
- โ
**Fixed**: Strict error handling - no more silent fallbacks when frames are missing
- โ
**Added**: Screenshot-level frame control (`frame: false` to disable per screenshot)
- โ
**Improved**: Better error messages when configuration issues occur
### v0.5.5
- โ ๏ธ Known issue: Missing PNG frame files in production (fixed in v0.5.6)
## ๐ 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "koubou",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "screenshot, app-store, graphics, automation, artisan, koubou",
"author": null,
"author_email": "David Collado <your-email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/51/d032d5b9a9f5f2ae4e00d45a6b4c7d9b20b114aee62d52cb0b7affb5a43d/koubou-0.6.0.tar.gz",
"platform": null,
"description": "# \ud83c\udfaf Koubou (\u5de5\u623f) - The Artisan Workshop for App Store Screenshots\n\n[](LICENSE)\n[](https://python.org/)\n[]()\n[](https://pypi.org/project/koubou/)\n\n**Koubou (\u5de5\u623f) transforms YAML into handcrafted App Store screenshots with artisan quality.**\n\n\u5de5\u623f (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## \u2728 Features\n\n- **\ud83d\udd04 Live Editing** - Real-time screenshot regeneration when config or assets change\n- **\ud83c\udf0d Multi-Language Localization** - Generate localized screenshots using familiar xcstrings format from Xcode\n- **\ud83c\udfa8 100+ Device Frames** - iPhone 16 Pro, iPad Air M2, MacBook Pro, Apple Watch Ultra, and more\n- **\ud83c\udf08 Professional Backgrounds** - Linear, radial, conic gradients with precise color control\n- **\u2728 Rich Typography** - Advanced text overlays with stroke, alignment, wrapping, and custom fonts\n- **\ud83c\udf08 Gradient Typography** - Linear, radial, and conic gradients for text with custom color stops\n- **\ud83d\udcf1 YAML-First Configuration** - Elegant, declarative screenshot definitions\n- **\ud83d\ude80 Batch Processing** - Generate multiple screenshots efficiently from a single config\n- **\ud83d\udd27 Flexible API** - Both simple and advanced configuration options\n- **\ud83d\udc8e Artisan Quality** - Pixel-perfect output ready for App Store submission\n\n## \ud83d\udce6 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## \ud83d\ude80 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## \ud83d\udd04 Live Editing\n\n**New in v0.5.0:** Koubou now supports real-time screenshot generation! The `live` command automatically regenerates screenshots when your YAML configuration or referenced assets change.\n\n```bash\n# Start live editing mode\nkou live my-screenshots.yaml\n\n# Optional: Adjust debounce delay (default: 0.5s)\nkou live my-screenshots.yaml --debounce 1.0\n\n# Enable verbose logging to see what's happening\nkou live my-screenshots.yaml --verbose\n```\n\n### How Live Editing Works\n\n1. **Smart Change Detection**: Monitors your YAML config file and all referenced assets\n2. **Selective Regeneration**: Only regenerates screenshots affected by changes\n3. **Dependency Tracking**: Automatically detects which assets each screenshot uses\n4. **Debounced Updates**: Prevents excessive regeneration during rapid edits\n\n### Live Editing Workflow\n\n```yaml\n# my-app-screenshots.yaml\nproject:\n name: \"My App\"\n output_dir: \"Screenshots/Generated\"\n\nscreenshots:\n welcome_screen:\n content:\n - type: \"image\"\n asset: \"app-screens/welcome.png\" # Live editing watches this file\n frame: true\n - type: \"text\"\n content: \"Welcome to the future\" # Changes to this regenerate instantly\n```\n\n**Perfect for iterative design workflows** - edit your assets in design tools, update text content, or tweak positioning, and see results instantly without manual regeneration!\n\n### Platform Support\n- **Live Editing**: macOS and Linux only\n- **Standard Generation**: macOS, Linux, and Windows\n\n---\n\n## \ud83c\udf0d Multi-Language Localization\n\nGenerate beautiful localized screenshots for international App Store submissions using the familiar xcstrings format from Xcode.\n\n### Quick Setup\n\nAdd a localization block to your YAML configuration:\n\n```yaml\nproject:\n name: \"My App Screenshots\"\n output_dir: \"Screenshots/Generated\"\n\n# Enable multi-language support\nlocalization:\n base_language: \"en\"\n languages: [\"en\", \"es\", \"ja\", \"fr\", \"de\"]\n xcstrings_path: \"Localizable.xcstrings\" # optional\n\nscreenshots:\n welcome_screen:\n content:\n - type: \"text\"\n content: \"Welcome to Amazing App\" # This becomes a 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### How It Works\n\n1. **Extract Text**: Koubou automatically finds all text content in your screenshots\n2. **Generate xcstrings**: Creates or updates your xcstrings file with text as localization keys\n3. **iOS-Familiar Format**: Edit translations in Xcode using the xcstrings editor you already know\n4. **Auto-Generate Screenshots**: Run `kou generate config.yaml` to create screenshots for all languages\n\n### Output Structure\n\n```\nScreenshots/Generated/\n\u251c\u2500\u2500 en/iPhone_15_Pro_Portrait/welcome_screen.png\n\u251c\u2500\u2500 es/iPhone_15_Pro_Portrait/welcome_screen.png \n\u251c\u2500\u2500 ja/iPhone_15_Pro_Portrait/welcome_screen.png\n\u251c\u2500\u2500 fr/iPhone_15_Pro_Portrait/welcome_screen.png\n\u2514\u2500\u2500 de/iPhone_15_Pro_Portrait/welcome_screen.png\n```\n\n### Live Editing with Localization\n\nLive mode works seamlessly with localization:\n\n```bash\nkou live config.yaml # Watches YAML config AND xcstrings file\n```\n\n- **Edit xcstrings in Xcode** \u2192 All language screenshots regenerate automatically\n- **Update YAML config** \u2192 xcstrings file updates with new text keys\n- **Change assets** \u2192 All localized versions update\n\n### Key Benefits\n\n- **\ud83c\udf4e iOS Developer Friendly**: Uses xcstrings format you already know from Xcode\n- **\ud83d\udd11 Natural Keys**: Your actual text becomes the localization key (no artificial IDs)\n- **\ud83c\udf0d Complete Localization**: Supports all xcstrings features including plurals and device variants\n- **\ud83d\ude80 Zero Extra Work**: Add localization block and run the same commands\n- **\ud83d\udd04 Live Updates**: Edit translations and see all screenshots update instantly\n\n---\n\n## \ud83c\udfa8 Configuration\n\nCreate elegant screenshots with YAML configuration:\n\n```yaml\nproject:\n name: \"My Beautiful App\"\n output_dir: \"Screenshots/Generated\"\n\ndevices:\n - \"iPhone 15 Pro Portrait\"\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\n### Advanced Configuration\n\n```yaml\nproject:\n name: \"Feature Showcase\"\n output_dir: \"Screenshots/Generated\"\n\ndevices:\n - \"iPhone 15 Pro Portrait\"\n\ndefaults:\n background:\n type: radial\n colors: [\"#ff9a9e\", \"#fecfef\", \"#feca57\"]\n\nscreenshots:\n ai_analysis:\n content:\n - type: \"text\"\n content: \"\u2728 AI-Powered Analysis\"\n position: [\"50%\", \"10%\"]\n size: 42\n color: \"#2c2c54\"\n weight: \"bold\"\n - type: \"text\"\n content: \"Smart insights at your fingertips\"\n position: [\"50%\", \"20%\"]\n size: 28\n color: \"#1A73E8\"\n - type: \"image\"\n asset: \"screenshots/analysis.png\"\n position: [\"50%\", \"65%\"]\n scale: 0.5\n frame: true\n```\n\n### Gradient Text Configuration\n\n```yaml\nscreenshots:\n gradient_showcase:\n content:\n - type: \"text\"\n content: \"\ud83c\udf08 Gradient Magic\"\n position: [\"50%\", \"15%\"]\n size: 48\n gradient:\n type: linear\n colors: [\"#FF6B6B\", \"#4ECDC4\", \"#45B7D1\"]\n direction: 45\n weight: \"bold\"\n - type: \"text\"\n content: \"Beautiful gradients for stunning text\"\n position: [\"50%\", \"25%\"]\n size: 24\n gradient:\n type: radial\n colors: [\"#667eea\", \"#764ba2\"]\n center: [\"50%\", \"50%\"]\n radius: \"70%\"\n - type: \"text\"\n content: \"Advanced Color Control\"\n position: [\"50%\", \"35%\"]\n size: 28\n gradient:\n type: linear\n colors: [\"#f093fb\", \"#f5576c\", \"#4facfe\"]\n positions: [0.0, 0.3, 1.0]\n direction: 90\n stroke_width: 2\n stroke_gradient:\n type: linear\n colors: [\"#333333\", \"#666666\"]\n direction: 45\n```\n\n## \ud83c\udfaf Commands\n\n### Core Commands\n\n- `kou generate <config.yaml>` - Generate screenshots from configuration\n- `kou live <config.yaml>` - **[New]** Live editing mode with real-time regeneration\n- `kou --create-config <output.yaml>` - 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## \ud83c\udfa8 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 & Watch Frames\n- MacBook Pro 2021 (14\" & 16\"), MacBook Air 2020/2022\n- iMac 24\" Silver, iMac 2021\n- Apple Watch Series 4/7, Watch Ultra\n\n## \ud83d\udcd6 YAML API Reference\n\n### Project Configuration\n```yaml\nproject:\n name: string # Project name\n output_dir: string # Output directory (default: \"output\")\n\ndevices: [string, ...] # Target device list (e.g., [\"iPhone 15 Pro Portrait\"])\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: # Screenshots are now organized by ID (breaking change in v0.5.0)\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? # Image file path (for type: \"image\")\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## \ud83c\udfd7\ufe0f 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## \ud83d\udd27 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## \ud83e\udd1d 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## \ud83d\udccb Changelog\n\n### v0.5.6 (Latest)\n- \u2705 **Fixed**: All device frame PNG files now properly included in production installations\n- \u2705 **Fixed**: Strict error handling - no more silent fallbacks when frames are missing\n- \u2705 **Added**: Screenshot-level frame control (`frame: false` to disable per screenshot)\n- \u2705 **Improved**: Better error messages when configuration issues occur\n\n### v0.5.5\n- \u26a0\ufe0f Known issue: Missing PNG frame files in production (fixed in v0.5.6)\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## \ud83c\udfaf Koubou Philosophy\n\nIn the spirit of Japanese craftsmanship, Koubou embodies:\n\n- **\u8077\u4eba\u6c17\u8cea (Shokunin-kishitsu)** - Artisan spirit and dedication to craft\n- **\u5b8c\u74a7 (Kanpeki)** - Pursuit of perfection in every detail \n- **\u7c21\u6f54 (Kanketsu)** - Elegant simplicity in design and usage\n- **\u54c1\u8cea (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.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 David Collado\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "\ud83c\udfaf Koubou (\u5de5\u623f) - The artisan workshop for App Store screenshots",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://koubou.readthedocs.io",
"Homepage": "https://github.com/bitomule/koubou",
"Issues": "https://github.com/bitomule/koubou/issues",
"Repository": "https://github.com/bitomule/koubou"
},
"split_keywords": [
"screenshot",
" app-store",
" graphics",
" automation",
" artisan",
" koubou"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "663f2ecf2500e07c479e5453bfc7ec1aa72a342875c15668d358cef5a1aafa0c",
"md5": "507025fecc8fa4ec73f7a0675e1dce09",
"sha256": "07eb1473bdde8fcc399f5b73e1a3d54f175ac0b0dd9f5771b56222b10cd6344a"
},
"downloads": -1,
"filename": "koubou-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "507025fecc8fa4ec73f7a0675e1dce09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 60030992,
"upload_time": "2025-09-02T22:24:08",
"upload_time_iso_8601": "2025-09-02T22:24:08.537264Z",
"url": "https://files.pythonhosted.org/packages/66/3f/2ecf2500e07c479e5453bfc7ec1aa72a342875c15668d358cef5a1aafa0c/koubou-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e651d032d5b9a9f5f2ae4e00d45a6b4c7d9b20b114aee62d52cb0b7affb5a43d",
"md5": "90f7497f77da0610c44b12afb10646b0",
"sha256": "72f326dbe064bd812b6bf008d2a5dd39ba635d487058ef45e6c2d2715b4f73b3"
},
"downloads": -1,
"filename": "koubou-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "90f7497f77da0610c44b12afb10646b0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 60002178,
"upload_time": "2025-09-02T22:24:12",
"upload_time_iso_8601": "2025-09-02T22:24:12.047064Z",
"url": "https://files.pythonhosted.org/packages/e6/51/d032d5b9a9f5f2ae4e00d45a6b4c7d9b20b114aee62d52cb0b7affb5a43d/koubou-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 22:24:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bitomule",
"github_project": "koubou",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "koubou"
}
