algorhythm 1.0.0
A Python library for real-time audio synthesis, pattern sequencing, and generative music.
License: MIT
Requires Python: >=3.7

# Algorhythm

*A Python audio synthesis and music composition library for real-time polyphonic sound generation*

Algorhythm is a powerful yet intuitive library for creating music programmatically using Python. It combines real-time audio synthesis, pattern sequencing, and music theory utilities to enable everything from simple melodies to complex generative compositions.

## Features

- **Real-time Audio Synthesis**: Multiple waveform generators (sine, square, saw, triangle, pulse, white noise, FM synthesis)
- **Polyphonic Playback**: Play multiple notes and layers simultaneously
- **Audio Effects**: Built-in ADSR envelopes, low-pass filtering, and LFO modulation
- **Pattern Sequencing**: Create and layer looping musical patterns with independent timing
- **Music Theory Tools**: Generate chords and note frequencies with equal temperament tuning
- **Audio Recording**: Capture your compositions to WAV files
- **Configurable Engine**: Customize sample rate, buffer size, and audio parameters
- **Thread-safe**: Designed for concurrent operation and live performance

## Installation

Install Algorhythm via pip:
```pip install algorhythm```

### Dependencies

- `numpy`: Signal processing and array operations
- `sounddevice`: Real-time audio I/O
- `scipy`: WAV file writing (for recording)

If you need to install the dependencies manually:
```pip install numpy sounddevice scipy``` 

## Quick Start

### Basic Audio Synthesis

```
from algorhythm.synth import initialize, add_note, SYNTHS

# Initialize audio engine with default settings
stream = initialize()
stream.start()

# Play a single note (A4 = 440Hz)
add_note(freq=440, duration=1.0, amplitude=0.5, synth_func=SYNTHS['sine'])

# Wait for playback to finish
import time
time.sleep(2)

# Cleanup
stream.stop()
stream.close()
```
---

### Custom Configuration
```
# Configure for low latency or high quality
stream = initialize(
    sample_rate=48000,      # Higher quality
    blocksize=512,          # Lower latency
    master_volume=0.2,      # Adjust overall volume
    channels=2              # Stereo output
)
stream.start()
```
---

### Playing Chords:
```
from algorhythm.chords_library import chord_notes

# Generate a C major chord in the 4th octave
c_major = chord_notes('C', 'major', 4)

# Play all notes in the chord
for note_name, octave, frequency in c_major:
    add_note(frequency, 2.0, 0.3, SYNTHS['sine'])
```
---

### Pattern Sequencing:
```
from algorhythm.patternlayer import PatternLayer

# Create an arpeggio pattern
arpeggio = PatternLayer(
    name="Arpeggio",
    pattern=[261.63, 329.63, 392.00],  # C, E, G (C major triad)
    intervals=[0.5, 0.5, 0.5],         # Play every 0.5 seconds
    durations=[0.4, 0.4, 0.4],         # Each note lasts 0.4 seconds
    amplitudes=[0.3, 0.3, 0.3],        # Constant volume
    synth='sine'
)

# Start the pattern (loops continuously)
arpeggio.start()

# Stop when done
time.sleep(5)
arpeggio.stop()
```

## Audio Effects

### ADSR Envelope:
```
# Create a note with attack, decay, sustain, and release
add_note(
    freq=440,
    duration=2.0,
    amplitude=0.6,
    synth_func=SYNTHS['saw'],
    env_params={
        'attack': 0.1,    # Fade in over 0.1 seconds
        'decay': 0.2,     # Decay to sustain level over 0.2 seconds
        'sustain': 0.7,   # Hold at 70% amplitude
        'release': 0.5    # Fade out over 0.5 seconds
    }
)
```
---

### Low-Pass Filter:
```
# Add filtering to remove harsh high frequencies
add_note(
    freq=440,
    duration=2.0,
    amplitude=0.6,
    synth_func=SYNTHS['square'],
    lpf_cutoff=1000  # Cut frequencies above 1000Hz
)
```
---

### LFO Modulation (Tremolo):
```
# Add vibrato/tremolo effect
add_note(
    freq=440,
    duration=3.0,
    amplitude=0.5,
    synth_func=SYNTHS['sine'],
    lfo_params={
        'lfo_freq': 5,      # Modulate 5 times per second
        'lfo_depth': 0.3    # 30% amplitude variation
    }
)
```
## Recording Audio

```
from algorhythm.synth import enable_recording, disable_recording, save_recording

# Start recording
enable_recording()

# Play your composition
add_note(440, 1.0, 0.5, SYNTHS['sine'])
time.sleep(2)

# Stop and save
disable_recording()
save_recording('output.wav')
```

## Available Synth Types

The `SYNTHS` dictionary provides quick access to the core waveforms and modulation types used in Algorhythm. Each type has a distinct sound character:

| Key         | Description                                       |
|-------------|---------------------------------------------------|
| `sine`      | Pure sine wave – smooth, fundamental tone         |
| `square`    | Square wave – hollow, clarinet-like               |
| `saw`       | Sawtooth wave – bright, buzzy                     |
| `triangle`  | Triangle wave – mellow, soft                      |
| `pulse`     | Pulse wave (20% duty cycle) – thin, nasal         |
| `noise`     | White noise – broadband random texture            |
| `fm`        | FM synthesis – bell-like, metallic                |

- **Sine**: The simplest and purest tone; contains only the fundamental frequency.
- **Square**: Hollow and reedy, rich in odd harmonics.
- **Saw**: Buzzy and bright, rich in both odd and even harmonics.
- **Triangle**: Softer and clearer than square, a gentle harmonic spectrum.
- **Pulse**: A variant of square with a thinner, more nasal sound due to a narrow duty cycle.
- **Noise**: Contains all frequencies, perfect for percussive or atmospheric sounds.
- **FM**: Frequency-modulated sine; produces complex, metallic, or bell-like timbres.

You can use any of these keys with the `SYNTHS` dictionary to select the desired waveform for synthesis.

## Advanced Example: Multi-Layer Composition
```
import threading
from algorhythm.synth import initialize, SYNTHS, enable_recording, disable_recording, save_recording
from algorhythm.patternlayer import PatternLayer

# Initialize
stream = initialize(master_volume=0.15)
stream.start()
enable_recording()

# Bass layer
bass = PatternLayer(
    name="Bass",
    pattern=[110, 110, 165, 110],  # A2, A2, E3, A2
    intervals=[0.5] * 4,
    durations=[0.3] * 4,
    amplitudes=[0.5, 0.3, 0.4, 0.3],
    synth='saw',
    lpf_cutoff=800,
    env_params={'attack': 0.01, 'decay': 0.1, 'sustain': 0.3, 'release': 0.2}
)

# Melody layer
melody = PatternLayer(
    name="Melody",
    pattern=[440, 494, 523, 494],  # A4, B4, C5, B4
    intervals=[0.25] * 4,
    durations=[0.2] * 4,
    amplitudes=[0.2] * 4,
    synth='sine'
)

# Start layers with timing
bass.start()
threading.Timer(2.0, melody.start).start()

# Play for 10 seconds
time.sleep(10)

# Cleanup
bass.stop()
melody.stop()
disable_recording()
save_recording('composition.wav')
stream.stop()
stream.close()
```

## Music Theory Utilities

### Generate Chords:
```
from algorhythm.chords_library import chord_notes, chord_inversion, list_chords

# Available chord types: 'major', 'minor', 'maj7', 'min7', 'dom7', 'sus2', 'sus4'

# Get chord notes with frequencies
em_chord = chord_notes('E', 'minor', 4)
# Returns: [('E', 4, 329.63), ('G', 4, 392.00), ('B', 4, 493.88)]

# Create inversions
first_inversion = chord_inversion(em_chord, 1)  # G in bass
second_inversion = chord_inversion(em_chord, 2) # B in bass

# List all chord types for a root
all_c_chords = list_chords('C', 4)
```

---

### Calculate Note Frequencies:
```
from algorhythm.chords_library import get_frequency

# Get frequency for any note and octave
a4_freq = get_frequency('A', 4)  # 440.0 Hz
c4_freq = get_frequency('C', 4)  # 261.63 Hz
```

## API Reference

### synth.py

- `initialize(**config)`: Configure and create audio stream
- `get_config()`: Get current engine configuration
- `add_note(freq, duration, amplitude, synth_func, **effects)`: Queue a note for playback
- `enable_recording()`: Start capturing audio output
- `disable_recording()`: Stop recording
- `save_recording(filename)`: Save recorded audio to WAV file

### patternlayer.py

- `PatternLayer.__init__(...)`: Create a pattern sequencer
- `PatternLayer.start()`: Begin playing the pattern
- `PatternLayer.stop()`: Stop playback
- `PatternLayer.update_pattern(**params)`: Modify pattern parameters in real-time

### chords_library.py

- `get_frequency(note, octave)`: Calculate frequency for a note
- `chord_notes(root_note, chord_type, octave)`: Generate chord note frequencies
- `chord_inversion(notes, inversion)`: Reorder notes for inversions
- `list_chords(root_note, octave)`: Get all chord types for a root

---

## Configuration Options

```
initialize(
    sample_rate=44100,        # Audio sample rate (Hz)
    blocksize=4096,           # Buffer size (samples)
    master_volume=0.15,       # Global volume (0.0-1.0)
    channels=2,               # 1=mono, 2=stereo
    use_fade_window=True,     # Adds fade to all notes
    fade_length=0.03,         # Fade duration (seconds)
    dtype='float32'           # Audio data type
)
```


---

## Requirements

- Python 3.7+
- NumPy >= 1.20.0
- sounddevice >= 0.4.0
- scipy >= 1.7.0

---

## License

MIT License – See LICENSE file for details

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

## Credits

Created by Niamh Callinan Keenan  
Created for algorithmic music composition and generative audio art.

---

**Happy composing! 🎵**