# 🌙 Moon Europa — Python Audio Library

> *Named after Europa, the icy moon of Jupiter — hiding an ocean beneath its frozen surface.*
> *Just like Europa conceals depths of mystery, this library gives you deep control over audio.*

Moon Europa (`mooneuropa`) is a comprehensive, batteries-included audio processing library for Python. Install it as `mooneuropa`, use it as `europa`.

## Installation

```bash
pip install mooneuropa
# with MP3 + visualization support:
pip install mooneuropa[all]
```

## Quick Start

```python
import europa

# Load audio
audio = europa.load("song.mp3")
print(audio)  # <Audio | mono | sr=22050 Hz | duration=180.0s>

# Playback
europa.play(audio)

# Record from microphone
rec = europa.record(5.0)

# Save
europa.save(audio, "output.wav")
```

## Feature Extraction

```python
mfcc     = europa.feature.mfcc(audio, n_mfcc=13)
mel      = europa.feature.mel_spectrogram(audio, n_mels=128)
chroma   = europa.feature.chroma(audio)
centroid = europa.feature.spectral_centroid(audio)
zcr      = europa.feature.zero_crossing_rate(audio)
rms      = europa.feature.rms_energy(audio)
tonnetz  = europa.feature.tonnetz(audio)
```

## Effects

```python
slow   = europa.effects.time_stretch(audio, rate=0.8)
higher = europa.effects.pitch_shift(audio, semitones=3)
bass   = europa.effects.low_pass(audio, cutoff=200)
bright = europa.effects.high_pass(audio, cutoff=5000)
loud   = europa.effects.gain(audio, db=6)
comp   = europa.effects.compress(audio, threshold_db=-20, ratio=4.0)
dist   = europa.effects.distort(audio, drive=10.0)
stereo = europa.effects.pan(audio, amount=0.5)
wet    = europa.effects.reverb(audio, room_size=0.7)
echo   = europa.effects.echo(audio, delay=0.3, decay=0.5)
faded  = europa.effects.fade_in(audio, duration=0.5)
clean  = europa.effects.noise_reduce(audio)
```

## Synthesis

```python
tone    = europa.synthesis.sine(440, duration=1.0)
buzz    = europa.synthesis.square(110, duration=2.0)
wn      = europa.synthesis.noise(1.0, color="white")
pn      = europa.synthesis.noise(1.0, color="pink")
note    = europa.synthesis.apply_adsr(tone, attack=0.01, decay=0.1, sustain=0.7, release=0.2)
c_major = europa.synthesis.chord([261.63, 329.63, 392.0], duration=2.0)
mixed   = europa.synthesis.mix(bass, drums, melody)
```

## Analysis

```python
bpm, beat_times = europa.analysis.beat_track(audio)
onsets          = europa.analysis.onset_detect(audio)
times, freqs    = europa.analysis.pitch_track(audio)
key             = europa.analysis.key_detect(audio)  # e.g. "A minor"
```

## Visualization

```python
europa.display.waveform(audio)
europa.display.spectrogram(audio)
europa.display.mel_spectrogram(audio)
europa.display.mfcc(audio)
europa.display.chroma(audio)
europa.display.beats(audio, beat_times)
europa.display.all_features(audio)
```

## Audio Object

```python
audio.duration   # float: seconds
audio.sr         # int: sample rate
audio.channels   # int: 1 or 2
audio.rms        # float
audio.peak       # float
audio.is_mono    # bool
audio.info()     # dict

clip   = audio.slice_time(1.0, 3.0)
joined = audio1 + audio2
```

## Dependencies

| Package     | Purpose                     |
|-------------|-----------------------------|
| numpy       | Core array operations       |
| scipy       | Filters, resampling, DCT    |
| soundfile   | WAV/FLAC/OGG I/O            |
| sounddevice | Playback & recording        |
| audioread   | MP3 decoding (optional)     |
| matplotlib  | Visualization (optional)    |

---

*🌙 "Beneath the ice, an ocean. Beneath the silence, sound."*
