# 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
