Spaces:
Sleeping
Sleeping
| title: Improvisation Lab | |
| emoji: 🎵 | |
| python_version: 3.11 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: gradio | |
| sdk_version: 5.7.1 | |
| app_file: main.py | |
| pinned: false | |
| license: mit | |
| # Improvisation Lab | |
| A Python package for generating musical improvisation melodies based on music theory principles. The package specializes in creating natural-sounding melodic phrases that follow chord progressions while respecting musical rules, with real-time pitch detection for practice feedback. | |
| ## Try it out! 🚀 | |
| <a href="https://huggingface.co/spaces/atsushieee/improvisation-lab" target="_blank"> | |
| <img src="https://img.shields.io/badge/🤗_Demo-Hugging_Face-FFD21E?style=for-the-badge&logo=huggingface&logoColor=black" alt="Hugging Face Spaces" /> | |
| </a> | |
| Watch the demo in action: | |
| https://github.com/user-attachments/assets/fa6e11d6-7b88-4b77-aa6e-a67c0927353d | |
| Experience Improvisation Lab directly in your browser! Our interactive demo lets you: | |
| - Generate melodic phrases based on chord progressions | |
| - Practice your pitch accuracy in real-time | |
| - Get instant visual guidance for hitting the right notes | |
| Note: The demo runs on Hugging Face Spaces' free tier, which means: | |
| - Performance might vary depending on server availability | |
| - If you encounter any issues, try refreshing the page or coming back later | |
| - For consistent performance, consider running the package locally | |
| ## Features | |
| - Generate melodic phrases based on scales and chord progressions | |
| - Support for multiple scale types: | |
| - Major | |
| - Natural minor | |
| - Harmonic minor | |
| - Diminished | |
| - Support for various chord types: | |
| - Major 7th (maj7) | |
| - Minor 7th (min7) | |
| - Dominant 7th (dom7) | |
| - Half-diminished (min7b5) | |
| - Diminished 7th (dim7) | |
| - Intelligent note selection based on: | |
| - Chord tones vs non-chord tones | |
| - Scale degrees | |
| - Previous note context | |
| - Real-time pitch detection with FCPE (Fast Context-aware Pitch Estimation) | |
| - Web-based and direct microphone input support | |
| ## Prerequisites | |
| - Python 3.11 or higher | |
| - A working microphone | |
| - [Poetry](https://python-poetry.org/) for dependency management | |
| ## Installation | |
| ```bash | |
| make install | |
| ``` | |
| ## Quick Start | |
| 1. Create your configuration file: | |
| ```bash | |
| cp config.yml.example config.yml | |
| ``` | |
| 2. (Optional) Edit `config.yml` to customize settings like audio parameters and song selection | |
| 3. Run the script to start the melody generation and playback (default is web interface): | |
| - Access the web interface at [http://127.0.0.1:7860/](http://127.0.0.1:7860/). | |
| ```bash | |
| make run | |
| ``` | |
| - To run the console interface, use: | |
| ```bash | |
| poetry run python main.py --app_type console | |
| ``` | |
| 4. Follow the displayed melody phrases and sing along with real-time feedback | |
| ### Configuration | |
| The application can be customized through `config.yml` with the following options: | |
| #### Audio Settings | |
| - `sample_rate`: Audio sampling rate (default: 44100 Hz) | |
| - `buffer_duration`: Duration of audio processing buffer (default: 0.2 seconds) | |
| - `note_duration`: How long to display each note during practice (default: 3 seconds) | |
| - `pitch_detector`: Configuration for the pitch detection algorithm | |
| - `hop_length`: Hop length for the pitch detection algorithm (default: 512) | |
| - `threshold`: Threshold for the pitch detection algorithm (default: 0.006) | |
| - `f0_min`: Minimum frequency for the pitch detection algorithm (default: 80 Hz) | |
| - `f0_max`: Maximum frequency for the pitch detection algorithm (default: 880 Hz) | |
| - `device`: Device to use for the pitch detection algorithm (default: "cpu") | |
| #### Song Selection | |
| - `selected_song`: Name of the song to practice | |
| - `chord_progressions`: Dictionary of songs and their progressions | |
| - Format: `[scale_root, scale_type, chord_root, chord_type, duration]` | |
| - Example: | |
| ```yaml | |
| fly_me_to_the_moon: | |
| - ["A", "natural_minor", "A", "min7", 4] | |
| - ["A", "natural_minor", "D", "min7", 4] | |
| - ["C", "major", "G", "dom7", 4] | |
| ``` | |
| ## How It Works | |
| ### Melody Generation | |
| The melody generation follows these principles: | |
| 1. Notes are selected based on their relationship to the current chord and scale | |
| 2. Chord tones have more freedom in movement | |
| 3. Non-chord tones are restricted to moving to adjacent scale notes | |
| 4. Phrases are connected naturally by considering the previous note | |
| 5. All generated notes stay within the specified scale | |
| ### Real-time Feedback | |
| Pitch Detection Demo: | |
| https://github.com/user-attachments/assets/fd9e6e3f-85f1-42be-a6c8-b757da478854 | |
| The application provides real-time feedback by: | |
| 1. Capturing audio from your microphone | |
| 2. Detecting the pitch using FCPE (Fast Context-aware Pitch Estimation) | |
| 3. Converting the frequency to the nearest musical note | |
| 4. Displaying both the target note and your sung note in real-time | |
| ## Development | |
| ### Running Lint | |
| ```bash | |
| make lint | |
| ``` | |
| ### Running Format | |
| ```bash | |
| make format | |
| ``` | |
| ### Running Tests | |
| ```bash | |
| make test | |
| ``` | |
| ## License | |
| MIT License | |
| ## Contributing | |
| Contributions are welcome! Please feel free to submit a Pull Request. | |