Metadata-Version: 2.4
Name: text-to-music-prompt-structurer
Version: 0.1.1
Summary: Turn free-form musical ideas into structured prompts for text-to-music workflows.
Author: Eduardo J. Barrios
License-Expression: MPL-2.0
Project-URL: Homepage, https://github.com/edujbarrios/text-to-music-prompt-structurer
Project-URL: Documentation, https://github.com/edujbarrios/text-to-music-prompt-structurer#readme
Project-URL: Repository, https://github.com/edujbarrios/text-to-music-prompt-structurer
Project-URL: Issues, https://github.com/edujbarrios/text-to-music-prompt-structurer/issues
Project-URL: Changelog, https://github.com/edujbarrios/text-to-music-prompt-structurer/blob/main/CHANGELOG.md
Keywords: music,prompt,text-to-music,suno,music-generation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# Text-to-Music Prompt Structurer

[![PyPI version](https://img.shields.io/pypi/v/text-to-music-prompt-structurer?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI&color=3775A9&cacheSeconds=300)](https://pypi.org/project/text-to-music-prompt-structurer/)
[![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-orange.svg?style=for-the-badge)](https://github.com/edujbarrios/text-to-music-prompt-structurer/blob/main/LICENSE)

Turn free-form musical ideas into structured prompts for text-to-music workflows.

The package detects genre, mood, BPM, key, instruments, production details, language, voice type, vocal tone, and vocal technique. It has no runtime dependencies and requires Python 3.10 or later.

## Install

```bash
python -m pip install text-to-music-prompt-structurer
```

## Command line

```bash
text-to-music-prompt "neo soul with piano, warm breathy female alto vocals in Spanish, intimate and melismatic, in d minor, nostalgic, 92 bpm"
```

Output:

```text
STYLE: Soul / Neo Soul
MOOD: Nostalgic, Warm
BPM: ~92
KEY: D Minor
INSTRUMENTS: Piano
PRODUCTION: Warm tone
VOCALS:
  LANGUAGE: Spanish
  VOICE TYPE: Female Lead, Alto
  TONE: Warm, Breathy, Intimate
  STYLE: Melismatic vocals
```

## Python

```python
from text_to_music_prompt_structurer import MusicPromptEngine, format_prompt

prompt = MusicPromptEngine().process(
    "synthwave with 808, dark and dreamy, female vocals in English"
)

print(format_prompt(prompt))
```

Output:

```text
STYLE: Synthwave
MOOD: Dark, Dreamy
INSTRUMENTS: 808 Bass
PRODUCTION: Dark tone
VOCALS:
  LANGUAGE: English
  VOICE TYPE: Female Lead
  TONE: Dark
```

`process()` returns a `MusicPrompt` object, so applications can use each detected value directly instead of parsing the formatted text. Its fields cover:

- Musical direction: `genre`, `subgenre`, `mood`, `energy`, `tempo`, `bpm`, and `key`.
- Arrangement and sound: `instruments`, `production`, `rhythm`, `structure`, and `era`.
- Vocal direction: `language`, `voice_type`, `vocal_tone`, and `vocal_style`.

`format_prompt()` renders only the detected fields as a ready-to-use structured prompt.

## Development

```bash
git clone https://github.com/edujbarrios/text-to-music-prompt-structurer.git
cd text-to-music-prompt-structurer
python -m pip install -e ".[dev]"
python -m pytest
ruff check .
```

See [CONTRIBUTING.md](CONTRIBUTING.md) to add vocabularies or detection strategies. Release history is available in [CHANGELOG.md](CHANGELOG.md).

## License

Copyright © 2026 Eduardo J. Barrios.

This project is licensed under the [Mozilla Public License 2.0](LICENSE). MPL 2.0 is a file-level copyleft license: modifications to covered source files must remain available under MPL 2.0, while those files may be combined with code under other licenses. See [NOTICE](NOTICE) for attribution details.

> [!NOTE]
> This is an unofficial tool and is not affiliated with, endorsed by, or connected to Suno AI.
