Metadata-Version: 2.4
Name: image2sound-newrealm
Version: 0.5.1
Summary: Turn images into short musical pieces via algorithmic sonification.
Author-email: Rami Pinku <rami@newrelam.co>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/newrealmco/image2sound
Project-URL: Issues, https://github.com/newrealmco/image2sound/issues
Project-URL: Changelog, https://github.com/newrealmco/image2sound/releases
Keywords: audio,music,sonification,image,ai,gradio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow
Requires-Dist: numpy
Requires-Dist: click
Provides-Extra: ui
Requires-Dist: gradio>=4.0; extra == "ui"
Provides-Extra: opencv
Requires-Dist: opencv-python-headless; extra == "opencv"
Provides-Extra: audio
Requires-Dist: soundfile; extra == "audio"
Provides-Extra: ml
Requires-Dist: scikit-learn; extra == "ml"
Provides-Extra: full
Requires-Dist: gradio>=4.0; extra == "full"
Requires-Dist: opencv-python-headless; extra == "full"
Requires-Dist: soundfile; extra == "full"
Requires-Dist: scikit-learn; extra == "full"
Dynamic: license-file

# image2sound
Turn images into short musical pieces via algorithmic sonification.

## Installation

### PyPI Installation
```bash
pip install image2sound-newrealm                # core only
pip install 'image2sound-newrealm[ui]'          # + Gradio UI
pip install 'image2sound-newrealm[opencv]'      # + OpenCV feature extraction
pip install 'image2sound-newrealm[audio]'       # + Soundfile output
pip install 'image2sound-newrealm[ml]'          # + scikit-learn clustering
pip install 'image2sound-newrealm[full]'        # all extras
```

### Development Setup (Current)
```bash
# Clone the repository
git clone https://github.com/newrealmco/image2sound.git
cd image2sound

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with UI support
pip install -e .[ui]
```

## Quickstart

### GUI (Recommended)
```bash
image2sound-ui
```
Opens a beautiful web interface in your browser where you can:
- Upload images with drag & drop
- Choose musical styles and settings  
- Watch real-time generation progress
- Play generated music instantly
- Download files and open in file manager

### Command Line
```bash
python -m image2sound.cli examples/demo.jpg -o out.wav --style ambient --duration 20
```

## How it works
- **Extract features**: Brightness, contrast, edge density, and 5-color palette from image
- **Map to music**: Hue → key, brightness → BPM/scale, contrast+edges → intensity
- **Compose arrangement**: 4/4 time with chords, lead melody, bass, and drums
- **Synthesize audio**: Sine waves with harmonics and ADSR, drums as noise bursts

## Styles
- **`neutral`**: Balanced mapping, piano/lead/drums
- **`ambient`**: Slower, major scale, soft pad/lead/bass instruments
- **`cinematic`**: Faster tempo, orchestral pad/lead/bass
- **`rock`**: Fastest, minor scale, piano/lead/drums with punch

## Examples
```bash
# Basic usage
python -m image2sound.cli photo.jpg

# Custom style and duration
python -m image2sound.cli landscape.png --style cinematic --duration 30

# Output to specific file
python -m image2sound.cli portrait.jpg -o music.wav --style rock --duration 15
```

## Batch demo
Generate a comprehensive demo set with musical metadata for analysis:
```bash
# Run batch processing on all images in examples/
python scripts/batch_demo.py

# Creates files like: bright_gradient_ambient_C_ionian_95bpm_4-4_I-V-vi-IV.wav
# Outputs CSV with: file,image,style,bpm,key,mode,meter,progression,seed,brightness,contrast,edge_density
```

The batch script processes all images in `examples/` with each of the 4 styles (neutral, ambient, cinematic, rock), creating descriptive filenames that include the musical parameters and outputting detailed CSV metadata for analysis.

## Development & Testing
```bash
# Install with development dependencies
pip install -e .[ui] -r requirements-dev.txt

# Run tests
pytest -q

# Test CLI
python -m image2sound.cli examples/demo.jpg -o out.wav --style ambient

# Test UI (opens in browser)
image2sound-ui
```
