fft-channel-vocoder 1.0.0__tar.gz

fft_channel_vocoder-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lawrence Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fft_channel_vocoder-1.0.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: fft_channel_vocoder
+Version: 1.0.0
+Summary: FFT-based channel vocoder that applies spectral envelope transfer
+Author: Your Name
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: mido
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# FFT Channel Vocoder
+
+> **Built by a blind programmer and musician, for musicians**
+
+A Python package that applies spectral envelope transfer using FFT-based processing. The vocoder takes a modulator (voice) signal and imposes its spectral envelope onto a carrier signal.
+
+Designed with accessibility as a core principle: CLI first, no GUI, cross-platform, automated batch processing—built by a blind developer for everyone who deserves equal access to audio tools.
+
+## Documentation
+
+- 📚 **[Documentation](docs/index.md)** — Installation, tutorials, configuration, and troubleshooting
+- 🎨 **[Design Philosophy](design/design.md)** — Why we built it this way, design decisions, and algorithm choices
+- ⚙️ **[Algorithm Deep Dive](design/algorithm.md)** — Technical details for audio engineers and researchers
+
+## Features
+
+- **Spectral Envelope Transfer**: Extracts formant information from voice and applies it to carrier signals
+- **Multiple Input Formats**: Supports voice files, MIDI files (synthesized to carrier waves), pre-generated synth wave files, and scale-based pitch correction
+- **Pitch Correction**: Optional automatic pitch detection and correction to user-defined musical scales with noise gate
+- **Batch Processing**: Automatically processes multiple input files with consistent naming patterns
+- **Generator-based Design**: Uses Python generators for efficient iteration through numbered file sequences
+- **Accessibility First**: CLI interface, fully accessible to screen readers, works across platforms
+
+## Installation
+
+### From source
+```bash
+cd fft_channel_vocoder
+pip install -e .
+```
+
+## Usage
+
+### Command Line
+
+Run the vocoder via the `vocode` command:
+```bash
+vocode
+```
+
+Or using Python module syntax:
+```bash
+python3 -m fft_channel_vocoder
+```
+
+### Input Structure
+
+The vocoder expects files organized in an `input/` directory:
+
+```
+input/
+├── voice1.wav          # Modulator signals
+├── voice2.wav
+├── melody1.mid         # MIDI files to synthesize as carrier
+├── melody2.mid
+├── synth1.wav          # Pre-generated synth wave files as carrier
+├── synth2.wav
+├── synth3.wav
+├── scale1.txt          # Scale files for pitch correction (one note per line)
+└── scale2.txt
+```
+
+**Scale File Format:**
+Each scale file contains one note class per line. Supported note classes are: `c`, `c#`, `d`, `d#`, `e`, `f`, `f#`, `g`, `g#`, `a`, `a#`, `b`. Comments (lines starting with `#`) and blank lines are ignored.
+
+Example `scale1.txt` (C Major scale):
+```
+# Major scale
+c
+d
+e
+f
+g
+a
+b
+```
+
+### Processing Flow
+
+For each voice file, the vocoder:
+
+1. **MIDI Processing**: Synthesizes each MIDI file into a carrier wave and vocodes with the voice
+2. **Synth Wave Processing**: Loads each pre-generated synth wave file and vocodes with the voice
+3. **Pitch Correction**: Detects pitch from the voice and snaps to a user-defined scale, synthesizes a carrier wave, and vocodes with the voice
+4. **Whisper Generation**: Creates a stereo whisper track by vocoding the voice with white noise
+
+**Pitch Correction Details:**
+- Analyzes the voice for dominant frequencies in the range 50-2000 Hz
+- Snaps detected pitches to a defined musical scale (octave-independent)
+- Uses a noise gate (-40 dB by default) to prevent unwanted tuning during silence or low-amplitude content
+- Maintains the last detected note when below the noise gate threshold
+
+### Output Structure
+
+Processed files are saved to `output/`:
+
+```
+output/
+├── voice1_melody1.wav       # Voice + MIDI synthesis
+├── voice1_melody2.wav
+├── voice1_synth1.wav        # Voice + Synth wave 1
+├── voice1_synth2.wav
+├── voice1_synth3.wav
+├── voice1_scale1.wav        # Voice + Pitch-corrected carrier (scale 1)
+├── voice1_scale2.wav        # Voice + Pitch-corrected carrier (scale 2)
+└── voice1_whisper.wav       # Stereo whisper track
+```
+
+## Configuration
+
+Edit `fft_channel_vocoder/config.py` to adjust:
+
+- `sample_rate`: Default 96,000 Hz
+- `fft_size`: FFT window power (2^12 = 4096 samples)
+
+## Algorithm
+
+The vocoder works in 4 steps:
+
+1. **STFT Analysis**: Compute Short-Time Fourier Transform for both voice and carrier
+2. **Spectral Smoothing**: Apply Gaussian blur to extract formant envelopes
+3. **Envelope Transfer**: Apply spectral whitening to the carrier, then scale by voice envelope
+4. **Reconstruction**: Inverse STFT with original carrier phase to recover time-domain signal
+
+## Demonstration
+
+Hear the FFT Vocoder in action:
+
+**[FFT Vocoder Demo Video](https://www.youtube.com/watch?v=-T7fRM0AHqs)** — Original voice, vocoded track, and vocoded track with music + code displayed on screen
+
+## Module Reference
+
+- `main.py`: Core pipeline and file iteration
+- `fft.py`: FFT vocoding algorithm
+- `clean_io.py`: Audio file I/O with resampling
+- `clean_audio.py`: Audio preprocessing and validation
+- `config.py`: Global configuration parameters
+- `midi_synth.py`: MIDI to audio synthesis
+- `pitch_corrector.py`: Pitch detection and scale-based note snapping
+- `scale_synth.py`: Pitch-corrected carrier synthesis
+- `noise_generators.py`: Noise generation utilities
+- `buffers.py`: Buffer management utilities
+
+## Disclaimer
+
+This project was developed with AI-assisted development. While some parts of the code were built with AI assistance, the program ideas, architecture, and design philosophy are original.

fft_channel_vocoder-1.0.0/README.md

@@ -0,0 +1,146 @@
+# FFT Channel Vocoder
+
+> **Built by a blind programmer and musician, for musicians**
+
+A Python package that applies spectral envelope transfer using FFT-based processing. The vocoder takes a modulator (voice) signal and imposes its spectral envelope onto a carrier signal.
+
+Designed with accessibility as a core principle: CLI first, no GUI, cross-platform, automated batch processing—built by a blind developer for everyone who deserves equal access to audio tools.
+
+## Documentation
+
+- 📚 **[Documentation](docs/index.md)** — Installation, tutorials, configuration, and troubleshooting
+- 🎨 **[Design Philosophy](design/design.md)** — Why we built it this way, design decisions, and algorithm choices
+- ⚙️ **[Algorithm Deep Dive](design/algorithm.md)** — Technical details for audio engineers and researchers
+
+## Features
+
+- **Spectral Envelope Transfer**: Extracts formant information from voice and applies it to carrier signals
+- **Multiple Input Formats**: Supports voice files, MIDI files (synthesized to carrier waves), pre-generated synth wave files, and scale-based pitch correction
+- **Pitch Correction**: Optional automatic pitch detection and correction to user-defined musical scales with noise gate
+- **Batch Processing**: Automatically processes multiple input files with consistent naming patterns
+- **Generator-based Design**: Uses Python generators for efficient iteration through numbered file sequences
+- **Accessibility First**: CLI interface, fully accessible to screen readers, works across platforms
+
+## Installation
+
+### From source
+```bash
+cd fft_channel_vocoder
+pip install -e .
+```
+
+## Usage
+
+### Command Line
+
+Run the vocoder via the `vocode` command:
+```bash
+vocode
+```
+
+Or using Python module syntax:
+```bash
+python3 -m fft_channel_vocoder
+```
+
+### Input Structure
+
+The vocoder expects files organized in an `input/` directory:
+
+```
+input/
+├── voice1.wav          # Modulator signals
+├── voice2.wav
+├── melody1.mid         # MIDI files to synthesize as carrier
+├── melody2.mid
+├── synth1.wav          # Pre-generated synth wave files as carrier
+├── synth2.wav
+├── synth3.wav
+├── scale1.txt          # Scale files for pitch correction (one note per line)
+└── scale2.txt
+```
+
+**Scale File Format:**
+Each scale file contains one note class per line. Supported note classes are: `c`, `c#`, `d`, `d#`, `e`, `f`, `f#`, `g`, `g#`, `a`, `a#`, `b`. Comments (lines starting with `#`) and blank lines are ignored.
+
+Example `scale1.txt` (C Major scale):
+```
+# Major scale
+c
+d
+e
+f
+g
+a
+b
+```
+
+### Processing Flow
+
+For each voice file, the vocoder:
+
+1. **MIDI Processing**: Synthesizes each MIDI file into a carrier wave and vocodes with the voice
+2. **Synth Wave Processing**: Loads each pre-generated synth wave file and vocodes with the voice
+3. **Pitch Correction**: Detects pitch from the voice and snaps to a user-defined scale, synthesizes a carrier wave, and vocodes with the voice
+4. **Whisper Generation**: Creates a stereo whisper track by vocoding the voice with white noise
+
+**Pitch Correction Details:**
+- Analyzes the voice for dominant frequencies in the range 50-2000 Hz
+- Snaps detected pitches to a defined musical scale (octave-independent)
+- Uses a noise gate (-40 dB by default) to prevent unwanted tuning during silence or low-amplitude content
+- Maintains the last detected note when below the noise gate threshold
+
+### Output Structure
+
+Processed files are saved to `output/`:
+
+```
+output/
+├── voice1_melody1.wav       # Voice + MIDI synthesis
+├── voice1_melody2.wav
+├── voice1_synth1.wav        # Voice + Synth wave 1
+├── voice1_synth2.wav
+├── voice1_synth3.wav
+├── voice1_scale1.wav        # Voice + Pitch-corrected carrier (scale 1)
+├── voice1_scale2.wav        # Voice + Pitch-corrected carrier (scale 2)
+└── voice1_whisper.wav       # Stereo whisper track
+```
+
+## Configuration
+
+Edit `fft_channel_vocoder/config.py` to adjust:
+
+- `sample_rate`: Default 96,000 Hz
+- `fft_size`: FFT window power (2^12 = 4096 samples)
+
+## Algorithm
+
+The vocoder works in 4 steps:
+
+1. **STFT Analysis**: Compute Short-Time Fourier Transform for both voice and carrier
+2. **Spectral Smoothing**: Apply Gaussian blur to extract formant envelopes
+3. **Envelope Transfer**: Apply spectral whitening to the carrier, then scale by voice envelope
+4. **Reconstruction**: Inverse STFT with original carrier phase to recover time-domain signal
+
+## Demonstration
+
+Hear the FFT Vocoder in action:
+
+**[FFT Vocoder Demo Video](https://www.youtube.com/watch?v=-T7fRM0AHqs)** — Original voice, vocoded track, and vocoded track with music + code displayed on screen
+
+## Module Reference
+
+- `main.py`: Core pipeline and file iteration
+- `fft.py`: FFT vocoding algorithm
+- `clean_io.py`: Audio file I/O with resampling
+- `clean_audio.py`: Audio preprocessing and validation
+- `config.py`: Global configuration parameters
+- `midi_synth.py`: MIDI to audio synthesis
+- `pitch_corrector.py`: Pitch detection and scale-based note snapping
+- `scale_synth.py`: Pitch-corrected carrier synthesis
+- `noise_generators.py`: Noise generation utilities
+- `buffers.py`: Buffer management utilities
+
+## Disclaimer
+
+This project was developed with AI-assisted development. While some parts of the code were built with AI assistance, the program ideas, architecture, and design philosophy are original.

fft_channel_vocoder-1.0.0/fft_channel_vocoder/__init__.py

@@ -0,0 +1,6 @@
+"""FFT Channel Vocoder - Apply spectral envelope transfer using FFT processing."""
+
+from .main import main, files_exist, whisper
+
+__version__ = "0.1.0"
+__all__ = ["main", "files_exist", "whisper"]

fft_channel_vocoder-1.0.0/fft_channel_vocoder/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for the fft_channel_vocoder package."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

fft_channel_vocoder-1.0.0/fft_channel_vocoder/buffers.py

@@ -0,0 +1,70 @@
+# buffers.py
+
+# holds a carrier buffer and synthesizer generators for MIDI and other purposes
+
+import numpy as np
+from .config import sample_rate
+
+
+class Carrier_Buffer:
+    """Pre-allocated audio buffer for building a carrier wave from note events."""
+
+    def __init__(self, total_duration):
+        """Allocate a silent buffer sized for the full duration.
+
+        Args:
+            total_duration: Length of the audio in seconds.
+        """
+        self.total_samples = int(np.ceil(total_duration * sample_rate))
+        self.carrier = np.zeros(self.total_samples, dtype=np.float32)
+
+    def add_wave(self, start_seconds, end_seconds, frequency):
+        """Mix a wave into the buffer over a time range.
+
+        Uses white noise for frequency <= 0 (silent/rest regions) and a
+        sawtooth wave otherwise.
+
+        Args:
+            start_seconds: Start time of the note in seconds.
+            end_seconds: End time of the note in seconds.
+            frequency: Pitch in Hz. Pass 0 or negative to write white noise.
+        """
+        # Safety check:
+        # Check if start is less than duration, and
+        # end is capped to the length if end_seconds is longer than duration.
+        start = int(round(start_seconds * sample_rate))
+        if start > self.total_samples:
+            raise ValueError("Start must be before duration")
+        end = min(int(round(end_seconds * sample_rate)), self.total_samples)
+        n = end - start
+        if n <= 0:
+            return
+        if frequency <= 0:
+            # Add white noise
+            self.carrier[start:end] += self.white_noise(n)
+        else:
+            # Append a wave with the frequency
+            self.carrier[start:end] += self.sawtooth_wave(frequency, n)
+
+
+    def sawtooth_wave(self, frequency, num_samples):
+        """Generate a sawtooth wave at the given frequency.
+
+        Args:
+            frequency: Pitch of the wave in Hz.
+            num_samples: Number of samples to generate.
+
+        Returns:
+            1D float32 numpy array of the sawtooth waveform in the range [-1, 1].
+        """
+        indices = np.arange(num_samples)
+        # Calculates phase from 0 to 1
+        phase = (frequency * indices / sample_rate) % 1.0
+        waveform = 2.0 * phase - 1.0
+        return waveform.astype(np.float32)
+
+
+    def white_noise(self, num_samples):
+        """Generate white noise."""
+        return np.random.uniform(-1.0, 1.0, num_samples).astype(np.float32)
+

fft_channel_vocoder-1.0.0/fft_channel_vocoder/clean_audio.py

@@ -0,0 +1,157 @@
+# clean_audio.py
+
+# Organized audio pypeline for Vocoder
+# handles the heavy DSP work before applying FFT vocoder, when loading and saving files.
+
+# Source of truth
+from .config import sample_rate
+# import other libraries
+import numpy as np
+from math import gcd
+from scipy.signal import resample_poly
+
+
+def make_stereo(left, right):
+    """
+    Validates two audio arrays and combines them into a stereo array.
+    Assumes audio_check(array, skip_mono_check) is already defined.
+    """
+    # Validate both arrays using your check function
+    # Ensuring skip_mono_check is False as requested
+    audio_check(left,skip_mono_check=False)
+    audio_check(right, skip_mono_check=False)
+    
+    # Check if they are the same length before stacking
+    if left.shape != right.shape:
+        raise ValueError(f"Arrays must have the same shape. Got {a.shape} and {b.shape}")
+
+    # Stack arrays along a new axis to create (samples, 2)
+    # np.stack(..., axis=-1) is standard for interleaved stereo
+    stereo_audio = np.column_stack((left, right))
+    
+    return stereo_audio
+
+
+
+def resample(audio, current_sample_rate):
+    """Resample audio to the project sample rate using polyphase filtering.
+
+    Args:
+        audio: Numpy array of audio samples.
+        current_sample_rate: The sample rate of the input audio in Hz.
+
+    Returns:
+        Numpy array resampled to the project sample rate, or the original
+        array unchanged if it already matches.
+    """
+    if current_sample_rate == sample_rate:
+        return audio
+
+    greatest_common_divisor = gcd(current_sample_rate, sample_rate)
+    up = sample_rate // greatest_common_divisor
+    down = current_sample_rate // greatest_common_divisor
+    return resample_poly(audio, up, down)
+
+def make_mono(audio):
+    """Convert a multi-channel audio array to mono by averaging channels.
+
+    Args:
+        audio: Numpy array of shape (samples,) or (samples, channels).
+
+    Returns:
+        1D numpy array. Already-mono input is returned unchanged.
+    """
+    if len(audio.shape) > 1:
+        return np.mean(audio, axis=1)
+    else:
+        return audio
+
+def convert_float32(audio):
+    """Convert an audio array to float32.
+
+    int16 input is scaled to the [-1.0, 1.0] range. Any other dtype is cast
+    directly to float32 without rescaling.
+
+    Args:
+        audio: Numpy array of audio samples.
+
+    Returns:
+        float32 numpy array.
+    """
+    if audio.dtype == np.int16:
+        return audio.astype(np.float32) / 32768.0
+    return audio.astype(np.float32)
+
+def normalise(audio):
+    """Normalise audio so the peak absolute value is 1.0.
+
+    Args:
+        audio: Numpy array of audio samples.
+
+    Returns:
+        Numpy array scaled so the loudest sample has magnitude 1.0.
+    """
+    # We use a small epsilon to avoid division by zero
+    norm_factor = np.max(np.abs(audio)) + 1e-9
+    return audio / norm_factor
+
+# Safety check - ensure audio is valid before processing
+
+def audio_check(audio, skip_mono_check=True):
+    """Validate that audio is a non-empty numpy array.
+
+    Args:
+        audio: The value to validate.
+        skip_mono_check: When False, also assert the array is 1D (mono).
+
+    Raises:
+        TypeError: If audio is not a numpy array.
+        ValueError: If audio is not mono (when skip_mono_check is False) or is empty.
+    """
+    if not isinstance(audio, np.ndarray):
+        raise TypeError(f"voice must be np.ndarray, got {type(audio)}")
+
+    if not skip_mono_check and audio.ndim != 1:
+        raise ValueError("Audio must be mono (1D arrays)")
+
+    if len(audio) == 0:
+        raise ValueError("Empty audio passed to vocoder")
+
+def clean(audio, current_sample_rate=None, skip_mono_conversion=False):
+    """Normalise and prepare an audio array for processing or saving.
+
+    Runs in order: validate → resample → make mono → convert to float32 →
+    normalise. Resampling is skipped when current_sample_rate is None or
+    already matches the project rate.
+
+    Args:
+        audio: Numpy array of audio samples.
+        current_sample_rate: Sample rate of the input audio in Hz, or None to
+            skip resampling.
+        skip_mono_conversion: When True, skip the make_mono step (needed when
+            saving stereo output).
+
+    Returns:
+        Cleaned float32 numpy array ready for processing or writing to disk.
+    """
+    # safety checks
+    audio_check(audio)
+    # If the synth returned an empty list or array, stop here
+    if audio is None or len(audio) == 0:
+        print("Warning: Received empty audio buffer in clean(). Returning silent array.")
+        return np.zeros(1024, dtype=np.float32) # Return a small slice of silence
+
+    # Change the sample rate if file_sample_rate is supplied
+    print("Fixing audio.")
+    if current_sample_rate is not None and current_sample_rate != sample_rate:
+        new_audio = resample(audio, current_sample_rate) # Avoid forshadowing
+    else:
+        new_audio = audio
+    # Make the track Mono
+    if not skip_mono_conversion:
+        new_audio = make_mono(new_audio)
+    # Convert to float 32
+    new_audio = convert_float32(new_audio)
+    # Convert to Mono
+    new_audio = normalise(new_audio)
+    return new_audio

fft_channel_vocoder-1.0.0/fft_channel_vocoder/clean_io.py

@@ -0,0 +1,55 @@
+# clean_io.py
+
+# responsible for opening and saving files and passing them as Numpy arrays, and cleaning up audio as soon as files are opened and saved.
+
+from .config import sample_rate
+from . import clean_audio
+import numpy as np
+from scipy.io import wavfile
+
+def does_exist(filename):
+    """Check whether a file exists on disk.
+
+    Args:
+        filename: Path-like or string path to check.
+
+    Returns:
+        True if the file can be opened for reading, False otherwise.
+    """
+    try:
+        with open(filename, "r") as f:
+            return True
+    except:
+        return False
+
+def load(filename):
+    """Load a WAV file and return a cleaned mono float32 array.
+
+    Resamples to the project sample rate if needed and runs the full
+    clean_audio pipeline.
+
+    Args:
+        filename: Path-like or string path to a WAV file.
+
+    Returns:
+        1D float32 numpy array normalised to [-1.0, 1.0].
+    """
+    #  Load the wav files
+    file_sample_rate, audio = wavfile.read(filename)
+
+    # Clean audio
+    return clean_audio.clean(audio, file_sample_rate)
+
+def save(filename, audio):
+    """Clean and write audio to a WAV file at the project sample rate.
+
+    Args:
+        filename: Destination path for the WAV file.
+        audio: Numpy array of audio samples to save. May be mono or stereo.
+    """
+    # Cleanup
+    new_audio = clean_audio.clean(audio, skip_mono_conversion=True)
+
+    # Save to file
+    wavfile.write(filename, sample_rate, new_audio.astype(np.float32))
+

fft_channel_vocoder-1.0.0/fft_channel_vocoder/config.py

@@ -0,0 +1,2 @@
+sample_rate = 96_000
+fft_size = 12