# 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
```
Raw data
{
"_id": null,
"home_page": null,
"name": "image2sound-newrealm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "audio, music, sonification, image, ai, gradio",
"author": null,
"author_email": "Rami Pinku <rami@newrelam.co>",
"download_url": "https://files.pythonhosted.org/packages/3d/a5/1d7540a0ee68a267cc4c0f23dabac49be42f4b5c72cf376401343ba1ed11/image2sound_newrealm-0.5.1.tar.gz",
"platform": null,
"description": "# image2sound\nTurn images into short musical pieces via algorithmic sonification.\n\n## Installation\n\n### PyPI Installation\n```bash\npip install image2sound-newrealm # core only\npip install 'image2sound-newrealm[ui]' # + Gradio UI\npip install 'image2sound-newrealm[opencv]' # + OpenCV feature extraction\npip install 'image2sound-newrealm[audio]' # + Soundfile output\npip install 'image2sound-newrealm[ml]' # + scikit-learn clustering\npip install 'image2sound-newrealm[full]' # all extras\n```\n\n### Development Setup (Current)\n```bash\n# Clone the repository\ngit clone https://github.com/newrealmco/image2sound.git\ncd image2sound\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install with UI support\npip install -e .[ui]\n```\n\n## Quickstart\n\n### GUI (Recommended)\n```bash\nimage2sound-ui\n```\nOpens a beautiful web interface in your browser where you can:\n- Upload images with drag & drop\n- Choose musical styles and settings \n- Watch real-time generation progress\n- Play generated music instantly\n- Download files and open in file manager\n\n### Command Line\n```bash\npython -m image2sound.cli examples/demo.jpg -o out.wav --style ambient --duration 20\n```\n\n## How it works\n- **Extract features**: Brightness, contrast, edge density, and 5-color palette from image\n- **Map to music**: Hue \u2192 key, brightness \u2192 BPM/scale, contrast+edges \u2192 intensity\n- **Compose arrangement**: 4/4 time with chords, lead melody, bass, and drums\n- **Synthesize audio**: Sine waves with harmonics and ADSR, drums as noise bursts\n\n## Styles\n- **`neutral`**: Balanced mapping, piano/lead/drums\n- **`ambient`**: Slower, major scale, soft pad/lead/bass instruments\n- **`cinematic`**: Faster tempo, orchestral pad/lead/bass\n- **`rock`**: Fastest, minor scale, piano/lead/drums with punch\n\n## Examples\n```bash\n# Basic usage\npython -m image2sound.cli photo.jpg\n\n# Custom style and duration\npython -m image2sound.cli landscape.png --style cinematic --duration 30\n\n# Output to specific file\npython -m image2sound.cli portrait.jpg -o music.wav --style rock --duration 15\n```\n\n## Batch demo\nGenerate a comprehensive demo set with musical metadata for analysis:\n```bash\n# Run batch processing on all images in examples/\npython scripts/batch_demo.py\n\n# Creates files like: bright_gradient_ambient_C_ionian_95bpm_4-4_I-V-vi-IV.wav\n# Outputs CSV with: file,image,style,bpm,key,mode,meter,progression,seed,brightness,contrast,edge_density\n```\n\nThe 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.\n\n## Development & Testing\n```bash\n# Install with development dependencies\npip install -e .[ui] -r requirements-dev.txt\n\n# Run tests\npytest -q\n\n# Test CLI\npython -m image2sound.cli examples/demo.jpg -o out.wav --style ambient\n\n# Test UI (opens in browser)\nimage2sound-ui\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Turn images into short musical pieces via algorithmic sonification.",
"version": "0.5.1",
"project_urls": {
"Changelog": "https://github.com/newrealmco/image2sound/releases",
"Issues": "https://github.com/newrealmco/image2sound/issues",
"Repository": "https://github.com/newrealmco/image2sound"
},
"split_keywords": [
"audio",
" music",
" sonification",
" image",
" ai",
" gradio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f1e07de1dc43a6dc3fdf83e1d284ecafa5bc76d6f2c34c2ba81715b8d4a883dc",
"md5": "213b360bb4cd6ec22093f89cd22db329",
"sha256": "5f62ec1393f63f88b09215bee3fa43e17e54348fac2a1e9cdc08abafc2b9462d"
},
"downloads": -1,
"filename": "image2sound_newrealm-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "213b360bb4cd6ec22093f89cd22db329",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 43978,
"upload_time": "2025-08-30T10:36:49",
"upload_time_iso_8601": "2025-08-30T10:36:49.360130Z",
"url": "https://files.pythonhosted.org/packages/f1/e0/7de1dc43a6dc3fdf83e1d284ecafa5bc76d6f2c34c2ba81715b8d4a883dc/image2sound_newrealm-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3da51d7540a0ee68a267cc4c0f23dabac49be42f4b5c72cf376401343ba1ed11",
"md5": "3e3a693c1fd22ef16f4de5574b04b4ab",
"sha256": "60219b32c9adbc5907f1b23df7ab89d22f60e235c8e6498c3d75cfc26622b804"
},
"downloads": -1,
"filename": "image2sound_newrealm-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "3e3a693c1fd22ef16f4de5574b04b4ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 47473,
"upload_time": "2025-08-30T10:36:50",
"upload_time_iso_8601": "2025-08-30T10:36:50.990361Z",
"url": "https://files.pythonhosted.org/packages/3d/a5/1d7540a0ee68a267cc4c0f23dabac49be42f4b5c72cf376401343ba1ed11/image2sound_newrealm-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 10:36:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "newrealmco",
"github_project": "image2sound",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.20.0"
]
]
},
{
"name": "opencv-python-headless",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "soundfile",
"specs": [
[
">=",
"0.10.0"
]
]
},
{
"name": "librosa",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
}
],
"lcname": "image2sound-newrealm"
}
JSON
