chipytune

<p align="center"> <img src="assets/ChiPyTune.png" alt="ChiPyTune" width="720"> </p> <p align="center"> <strong>Source-available Game Boy style music and SFX creation for desktop, CLI, HTTP, and MCP workflows.</strong> </p> <p align="center"> <a href="USER_GUIDE.md">User Guide</a> | <a href="CONTRIBUTING.md">Contributing</a> | <a href="SECURITY.md">Security</a> | <a href="CODE_OF_CONDUCT.md">Code of Conduct</a> | <a href="LICENSE.md">License</a> </p> <p align="center"> <img alt="Python" src="https://img.shields.io/badge/python-3.13-blue"> <img alt="GUI" src="https://img.shields.io/badge/gui-PySide6%2FQt-41cd52"> <img alt="License" src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-orange"> <img alt="Status" src="https://img.shields.io/badge/status-alpha-8b5cf6"> </p> ## What Is Chipytune? Chipytune is a source-available non-commercial tool for creating Game Boy style chiptune music and sound effects. It produces editable JSON projects and renders them to WAV/OGG audio through the same core service used by every interface. Chipytune is Game Boy style. It is not a cycle-accurate Game Boy APU emulator. Use it to: - sketch block-based music in the Hobbista desktop mode; - edit detailed tracker-style projects in the Profissional desktop mode; - generate and render JSON from the CLI; - expose local render/validation endpoints over HTTP; - let MCP-capable clients create, validate, and render music or SFX. ## Desktop Experience <p align="center"> <img src="assets/professional.png" alt="Chipytune Profissional mode" width="900"> </p> <p align="center"> <strong>Profissional mode</strong><br> Full tracker, instrument, preset, SFX, JSON, preview, and export workflow for detailed editing. </p> <p align="center"> <img src="assets/hobbie.png" alt="Chipytune Hobbista mode" width="900"> </p> <p align="center"> <strong>Hobbista mode</strong><br> A playful block composer with a fixed-width scrollable timeline for fast musical sketching. </p> ## Current Status Chipytune is an alpha-stage creative tool. The recommended way to run it today is from source with `uv`. Nuitka onefile scripts exist for local experimental builds, but they are not the official release path right now. Working today: - Desktop GUI with Hobbista and Profissional modes. - Local GUI language switching: `pt_BR`, `es_ES`, and `en_US`. - Music project schema: `chipytune.project.v1`. - SFX project schema: `chipytune.sfx.v1`. - WAV and OGG rendering. - WAV/OGG metadata tags for title, artist, album, genre, and track number. - Built-in music and SFX presets. - CLI, HTTP API, and MCP server entry points. ## Screens And Assets - Project banner: `assets/ChiPyTune.png`. - Application icon: `assets/icon.png`. - Profissional screenshot: `assets/professional.png`. - Hobbista screenshot: `assets/hobbie.png`. - Packaged Qt icon asset: `src/chipytune/gui/assets/icon.png`. The root `assets/icon.png` is the canonical system icon for project presentation. The packaged copy is used by the PySide6 application at runtime. ## Runtime Support The documented and supported runtime path is Linux with `uv`. Other operating systems may work for source runs or local builds, but they are not guaranteed by this project right now. If you are consuming Chipytune from Windows, the recommended setup is to run the MCP server on Linux and connect to it remotely from the Windows MCP client. ## Requirements - Python `>=3.13,<3.14`. - `uv` for dependency management. - PySide6/Qt for the desktop application. - Native audio support through `python-soundfile`/`libsndfile`. - Vorbis support in `libsndfile` for OGG export. ## Install From Source ```bash uv sync --all-groups bash scripts/build-gui-translations.sh ``` Run full verification: ```bash uv run ruff format . uv run ruff check . uv run mypy src uv run pytest -q ``` Expected current test result: `153 passed, 2 skipped`. ## Quick Start: Desktop GUI ```bash uv run chipytune gui ``` The GUI opens in Profissional mode. Click `Open Hobbista` to switch to the simpler block composer. Hobbista mode is best for fast composition: - generate a guided base; - place fixed-width music blocks on a scrollable timeline; - edit melody, harmony, bass, and drums visually; - preview, save, open, and export without touching JSON. Profissional mode is best for detailed editing: - manage presets and metadata; - edit instruments; - edit tracker-grid music patterns; - edit SFX timelines; - inspect and apply raw JSON; - preview and export projects. See the full [User Guide](USER_GUIDE.md) for detailed GUI usage in Portuguese, Spanish, and English. ## Quick Start: CLI Create and render a music loop: ```bash uv run chipytune template music --name gameboy-loop --out examples/gameboy_loop.json uv run chipytune validate examples/gameboy_loop.json uv run chipytune render examples/gameboy_loop.json --out dist/audio --stem gameboy_loop ``` Create and render a jump SFX: ```bash uv run chipytune template sfx --name jump --out examples/jump_sfx.json uv run chipytune validate examples/jump_sfx.json uv run chipytune render examples/jump_sfx.json --out dist/audio --stem jump ``` Export every built-in preset as a game asset pack: ```bash uv run chipytune presets export --out dist/game-assets ``` ## Built-In Presets Music: - `gameboy-loop` - `pulse-bass-loop` SFX: - `jump` - `coin` - `laser` - `explosion` - `powerup` - `hit` - `select` - `error` ## JSON Project Model Chipytune JSON is the source of truth. The GUI, CLI, HTTP API, and MCP server all validate and render the same schemas. Music projects use: ```json "schema_version": "chipytune.project.v1" ``` SFX projects use: ```json "schema_version": "chipytune.sfx.v1" ``` Generate schemas: ```bash uv run chipytune schema project --out dist/project.schema.json uv run chipytune schema sfx --out dist/sfx.schema.json ``` ## HTTP API Start the local API server: ```bash uv run chipytune http serve --host 127.0.0.1 --port 8000 ``` Useful endpoints: - `GET /health` - `GET /v1/schema/project` - `GET /v1/schema/sfx` - `GET /v1/presets` - `POST /v1/projects/validate` - `POST /v1/projects/render` - `POST /v1/sfx/validate` - `POST /v1/sfx/render` ## MCP Server Local stdio mode, when the MCP client starts Chipytune on the same machine: ```bash uv run chipytune mcp serve --transport stdio ``` Remote HTTP mode, when another machine consumes the MCP server over the network: ```bash uv run chipytune mcp serve --transport streamable-http --host 0.0.0.0 --port 8765 ``` The remote command listens on all network interfaces and disables FastMCP DNS rebinding protection for that process. Use it only on a trusted local network or behind your own firewall/VPN. Supported transports: - `stdio` - `sse` - `streamable-http` Registered tools: - `chipytune_get_project_schema` - `chipytune_get_sfx_schema` - `chipytune_list_presets` - `chipytune_create_template` - `chipytune_validate_project` - `chipytune_render_music` - `chipytune_validate_sfx` - `chipytune_render_sfx` Typical opencode remote client configuration: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "chipytune": { "type": "remote", "enabled": true, "url": "http://LINUX_SERVER_IP:8765/mcp" } } } ``` Typical opencode local stdio configuration: ```json { "mcpServers": { "chipytune": { "command": "uv", "args": ["run", "chipytune", "mcp", "serve", "--transport", "stdio"], "cwd": "/path/to/chipytune" } } } ``` Development smoke test: ```bash uv run pytest tests/test_mcp.py -q ``` ## Local Binary Builds The recommended usage path is Linux source + `uv`. Binary builds are experimental local artifacts. If you need one, build it on the target OS and test GUI startup, system audio playback, export, and native audio dependencies on that machine. No cross-OS compatibility is guaranteed. Linux: ```bash bash scripts/build-headless-linux.sh bash scripts/build-gui-linux.sh ``` Windows build scripts may exist in the repository, but Windows is not a documented or guaranteed runtime target right now. Optional slow smoke tests: ```bash CHIPYTUNE_RUN_NUITKA_SMOKE=1 uv run pytest tests/test_packaging_smoke.py -q CHIPYTUNE_RUN_NUITKA_GUI_SMOKE=1 uv run pytest tests/test_packaging_smoke.py -q ``` ## Documentation - [User Guide](USER_GUIDE.md): complete usage guide in Portuguese, Spanish, and English. - [MCP Game Audio Asset Integration](MCP_GAME_ASSET_INTEGRATION.md): agent-facing guide for creating game music and SFX through MCP. - [Contributing](CONTRIBUTING.md): local setup, contribution process, testing, and style. - [Security](SECURITY.md): supported versions and vulnerability reporting. - [Code of Conduct](CODE_OF_CONDUCT.md): community behavior expectations. - [License](LICENSE.md): PolyForm Noncommercial License 1.0.0. ## Contributing Contributions are welcome for non-commercial development under this repository's license terms. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening pull requests. Priorities: - keep JSON schemas stable and explicit; - keep GUI, CLI, HTTP, and MCP on the shared service layer; - add tests for behavior changes; - avoid duplicating render logic outside `src/chipytune/services.py`. ## Security Please do not publish exploit details in public issues. See [SECURITY.md](SECURITY.md) for the reporting process. ## License Chipytune uses the [PolyForm Noncommercial License 1.0.0](LICENSE.md). This means Chipytune is source-available for non-commercial use. It is not OSI open-source software. Generated outputs are different from the software itself. You may sell games, audio files, and other assets you create with Chipytune. You may not sell, sublicense, host, or redistribute Chipytune itself commercially except under the project license or a separate commercial license from the rights holder.