Metadata-Version: 2.4
Name: melogenai
Version: 0.1.0
Summary: Python SDK for Melogen AI - AI-powered music tools
Project-URL: Homepage, https://melogenai.com
Project-URL: Documentation, https://melogenai.com/zh/faq
Project-URL: Repository, https://github.com/melogenai/melogenai-python
Project-URL: Issues, https://github.com/melogenai/melogenai-python/issues
Author-email: Melogen AI <dev@melogenai.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,audio,midi,music,sheet-music,transcription
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# melogenai — python sdk & cli for ai-powered music tools

[![PyPI](https://img.shields.io/pypi/v/melogenai.svg)](https://pypi.org/project/melogenai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

python sdk and cli for [melogen ai](https://melogenai.com) — convert sheet music to MIDI, transcribe audio to MIDI, and analyze music structure.

supports sync and async clients, streaming analysis, and a full-featured cli. convert PDFs, images, and audio files to MIDI with a single function call.

## Installation

```bash
pip install melogenai
```

## Quick Start

### Python SDK

```python
from melogenai import Melogen

client = Melogen(api_key="melo_xxx")

# Convert sheet music to MIDI
result = client.sheet2midi.convert(file_url="https://example.com/score.pdf")
final = client.sheet2midi.wait(result.task_id)
print(final.download_urls)

# Convert audio to MIDI
result = client.music2midi.convert(file_url="https://example.com/song.mp3")
final = client.music2midi.wait(result.task_id)
print(final.download_urls)

# Analyze music structure (streaming)
for chunk in client.analysis.analyze_stream(image_url="https://example.com/score.png"):
    print(chunk, end="")
```

### Async

```python
from melogenai import AsyncMelogen

async with AsyncMelogen(api_key="melo_xxx") as client:
    result = await client.sheet2midi.convert(file_url="https://example.com/score.pdf")
    final = await client.sheet2midi.wait(result.task_id)
    print(final.download_urls)
```

### CLI

```bash
# Set your API key
export MELOGEN_API_KEY=melo_xxx

# Convert sheet music
melogen sheet2midi https://example.com/score.pdf

# Convert audio to MIDI
melogen music2midi https://example.com/song.mp3 --stems --quantize

# Analyze music
melogen analysis --image https://example.com/score.png --lang zh

# Verify API key
melogen auth verify
```

## Services

| Service | Description | Input | Output |
|---------|-------------|-------|--------|
| `sheet2midi` | Sheet music to MIDI | PDF, PNG, JPG | MIDI, MusicXML |
| `music2midi` | Audio to MIDI | MP3, WAV, FLAC, OGG, M4A | MIDI |
| `analysis` | Music structure analysis | MusicXML, image, PDF | Structured text |

## Configuration

| Parameter | Env Var | Default |
|-----------|---------|---------|
| `api_key` | `MELOGEN_API_KEY` | (required) |
| `base_url` | `MELOGEN_BASE_URL` | `https://api.melogen.ai` |
| `timeout` | - | `30.0` |
| `poll_interval` | - | `2.0` |
| `poll_timeout` | - | `300.0` |

## Error Handling

```python
from melogenai import Melogen, AuthenticationError, TaskTimeoutError

client = Melogen(api_key="melo_xxx")

try:
    result = client.sheet2midi.convert(file_url="https://example.com/score.pdf")
    final = client.sheet2midi.wait(result.task_id)
except AuthenticationError:
    print("Invalid API key")
except TaskTimeoutError:
    print("Task took too long")
```

| Exception | HTTP Status | Cause |
|-----------|-------------|-------|
| `AuthenticationError` | 401 | Invalid or expired API key |
| `InsufficientCreditsError` | 402 | Account out of credits |
| `ValidationError` | 422 | Invalid parameters or unsupported format |
| `RateLimitError` | 429 | Too many requests |
| `TaskTimeoutError` | — | Processing exceeded timeout |
| `TaskFailedError` | — | Server-side processing error |

## Claude Code Skill

Install the [melogen skill](https://github.com/melogenai/skills) to use melogen directly in claude code:

```bash
npx @anthropic-ai/claude-code skills add melogenai/skills@melogen
```

## Links

- **Website**: [melogenai.com](https://melogenai.com)
- **FAQ**: [melogenai.com/zh/faq](https://melogenai.com/zh/faq)
- **Skills**: [github.com/melogenai/skills](https://github.com/melogenai/skills)
- **PyPI**: [pypi.org/project/melogenai](https://pypi.org/project/melogenai/)

## License

MIT
