cycdp 0.1.1__tar.gz → 0.1.2__tar.gz

{cycdp-0.1.1 → cycdp-0.1.2}/.github/workflows/build-publish.yml

@@ -17,8 +17,9 @@ on:
         type: boolean
 
 env:
-  CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*-*"
-  CIBW_SKIP: "*-musllinux_* pp*"
+  # Note: cp314 excluded due to Cython compatibility issues on macOS x86_64
+  CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-* cp314-*"
+  CIBW_SKIP: "*-musllinux_*"
   CIBW_TEST_REQUIRES: pytest
   CIBW_TEST_COMMAND: pytest {project}/tests -v
 
@@ -48,6 +49,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: arm64
+
       - name: Build wheels
         uses: pypa/cibuildwheel@v3.3.1
         env:

{cycdp-0.1.1 → cycdp-0.1.2}/CHANGELOG.md

@@ -7,11 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2]
+
+### Added
+
+- Command-line interface accessible via `cycdp` console script and `python3 -m cycdp`
+  - All 100+ audio processing functions exposed as flat subcommands (e.g. `cycdp time-stretch`, `cycdp reverb`)
+  - Four input modes: single-file processing, dual-file processing (morph, mix), synthesis (no input), and analysis (text/JSON/CSV output)
+  - `cycdp list [category]` for category-grouped command discovery
+  - `cycdp info <file>` for audio file metadata
+  - `cycdp version` for version information
+  - Global options: `-o/--output` (file or directory), `-n/--normalize`, `--no-normalize`, `--format`
+  - Automatic output naming when `-o` is omitted (`<input_stem>_<command>.wav`)
+  - Category-grouped `--help` output via custom formatter
+- Type stubs (`_core.pyi`) for IDE autocompletion and type checking
+- PyPI publication metadata (URLs, classifiers, keywords)
+
+### Fixed
+
+- Buffer overflow in `cdp_flutter.c` mono-to-stereo conversion causing segfaults
+- Variable Length Array (VLA) compatibility for MSVC in `io.c`
+- `M_PI` undefined error for MSVC in `utils.c`
+- Linux build failure by enabling position-independent code
+
 ## [0.1.1]
 
 ### Added (Demos)
 
 **Synthesis Demos (01-07)** - Generate test sounds and demonstrate API:
+
 - `01_basic_operations.py` - Buffers, gain, fades, panning, mixing
 - `02_effects_and_processing.py` - Delay, reverb, modulation, distortion, filters
 - `03_spectral_processing.py` - Blur, focus, time stretch, pitch shift, freeze
@@ -21,6 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `07_morphing.py` - Spectral morph, glide, cross-synthesis
 
 **FX Processing Demos (fx01-fx07)** - CLI tools for processing real audio:
+
 - `fx01_time_and_pitch.py` - Time stretch, pitch shift, spectral shift
 - `fx02_spectral_effects.py` - Blur, focus, fold, freeze effects
 - `fx03_granular.py` - Brassage, wrappage, grain operations
@@ -32,23 +57,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 All FX demos accept `input.wav -o output_dir/` arguments.
 
 **Makefile targets:**
+
 - `make demos` - Run all demos, output to `build/`
 - `make demos-clean` - Remove generated WAV files
 
 ### Added (CDP Algorithm Ports)
 
 **Analysis:**
+
 - `pitch` - pitch tracking using YIN algorithm (CDP: pitch)
 - `formants` - formant analysis using LPC (CDP: formants)
 - `get_partials` - partial/harmonic tracking (CDP: get_partials)
 
 **Spectral Processing:**
+
 - `spectral_focus` - super-Gaussian frequency enhancement (CDP: focus)
 - `spectral_hilite` - boost spectral peaks above threshold (CDP: hilite)
 - `spectral_fold` - fold spectrum at frequency for metallic effects (CDP: specfold)
 - `spectral_clean` - spectral noise gate (CDP: speclean)
 
 **Experimental/Chaos:**
+
 - `strange` - Lorenz attractor chaotic modulation (CDP: strange)
 - `brownian` - random walk modulation of pitch/amp/filter (CDP: brownian)
 - `crystal` - crystalline textures with decaying echoes (CDP: crystal)
@@ -61,6 +90,7 @@ All FX demos accept `input.wav -o output_dir/` arguments.
 - `tesselate` - tile-based pattern transformations (CDP: tesselate)
 
 **Playback/Time Manipulation:**
+
 - `zigzag` - alternating forward/backward playback through time points (CDP: zigzag)
 - `iterate` - repeated playback with pitch/gain variations (CDP: iterate)
 - `stutter` - segment-based stuttering with silence inserts (CDP: stutter)
@@ -77,11 +107,13 @@ All FX demos accept `input.wav -o output_dir/` arguments.
 - `wrappage` - granular texture with stereo spatial distribution (CDP: wrappage)
 
 **Spatial Effects:**
+
 - `spin` - rotate audio around stereo field with optional doppler (CDP: spin)
 - `rotor` - dual-rotation modulation creating interference patterns (CDP: rotor)
 - `flutter` - spatial tremolo with loudness modulation alternating L/R (CDP: flutter)
 
 **Extended Granular:**
+
 - `grain_reorder` - reorder detected grains (shuffle, reverse, rotate) (CDP: grain)
 - `grain_rerhythm` - change timing/rhythm of grains (CDP: grain)
 - `grain_reverse` - reverse individual grains in place (CDP: grain)
@@ -92,12 +124,14 @@ All FX demos accept `input.wav -o output_dir/` arguments.
 - `grain_duplicate` - duplicate grains with variations (CDP: grain)
 
 **Granular/Texture:**
+
 - `grain_cloud` - grain cloud generation from amplitude-detected grains (CDP: grain)
 - `grain_extend` - extend duration using grain repetition (CDP: grainex extend)
 - `texture_simple` - simple texture layering (CDP: texture SIMPLE_TEX)
 - `texture_multi` - multi-layer grouped texture (CDP: texture GROUPS)
 
 **Morphing/Cross-synthesis:**
+
 - `morph` - spectral interpolation between two sounds (CDP: SPECMORPH)
 - `morph_glide` - simple spectral glide between two sounds (CDP: SPECGLIDE)
 - `cross_synth` - combine amp from one sound with freq from another (CDP: combine)
@@ -106,24 +140,28 @@ All FX demos accept `input.wav -o output_dir/` arguments.
 - `morph_native` - native CDP specmorph wrapper (original algorithm)
 
 **Synthesis:**
+
 - `synth_wave` - waveform synthesis (sine, square, saw, ramp, triangle) (CDP: wave)
 - `synth_noise` - noise generation (white, pink) (CDP: synth noise)
 - `synth_click` - click/metronome track generation (CDP: click)
 - `synth_chord` - chord synthesis from MIDI pitch list (CDP: multi_syn)
 
 **Pitch-Synchronous Operations (PSOW):**
+
 - `psow_stretch` - time-stretch while preserving pitch using PSOLA (CDP: psow stretch)
 - `psow_grab` - extract pitch-synchronous grains from a position (CDP: psow grab)
 - `psow_dupl` - duplicate grains for time-stretching (CDP: psow dupl)
 - `psow_interp` - interpolate between two grains (CDP: psow interp)
 
 **FOF Extraction and Synthesis (FOFEX):**
+
 - `fofex_extract` - extract single FOF at specified time (CDP: fofex)
 - `fofex_extract_all` - extract all FOFs to uniform-length bank (CDP: fofex)
 - `fofex_synth` - synthesize audio from FOFs at target pitch (CDP: fofex)
 - `fofex_repitch` - repitch audio with optional formant preservation (CDP: fofex)
 
 **Distortion:**
+
 - `distort_cut` - waveset segmentation with decaying envelope (CDP: distcut)
 - `distort_mark` - interpolate between waveset groups at time markers (CDP: distmark)
 - `distort_repeat` - time-stretch by repeating wavecycles (CDP: distrep)
@@ -131,6 +169,7 @@ All FX demos accept `input.wav -o output_dir/` arguments.
 - `distort_warp` - progressive warp distortion with modular sample folding (CDP: distwarp)
 
 **Filtering:**
+
 - `filter_bandpass` - spectral bandpass filter
 - `filter_notch` - spectral notch (band-reject) filter
 
@@ -139,9 +178,11 @@ All FX demos accept `input.wav -o output_dir/` arguments.
 Standard DSP functions not derived from CDP algorithms:
 
 **EQ:**
+
 - `eq_parametric` - parametric equalizer with center frequency, gain, and Q factor
 
 **Dynamics:**
+
 - `gate` - noise gate with attack/release/hold envelope
 - `compressor` - dynamic range compression with threshold, ratio, attack/release
 - `limiter` - peak limiting with attack/release
@@ -149,6 +190,7 @@ Standard DSP functions not derived from CDP algorithms:
 - `envelope_apply` - apply envelope to sound with depth control
 
 **Effects:**
+
 - `bitcrush` - bit depth and sample rate reduction
 - `ring_mod` - ring modulation with carrier frequency
 - `delay` - feedback delay with mix control
@@ -161,12 +203,14 @@ Standard DSP functions not derived from CDP algorithms:
 - Scramble modes: `SCRAMBLE_SHUFFLE`, `SCRAMBLE_REVERSE`, `SCRAMBLE_SIZE_UP`, `SCRAMBLE_SIZE_DOWN`, `SCRAMBLE_LEVEL_UP`, `SCRAMBLE_LEVEL_DOWN`
 
 ### Fixed
+
 - Phase vocoder frequency calculation now uses correct hop size
 - Spectral filters now use bin center frequency for accurate filtering
 
 ## [0.1.0]
 
 ### Added
+
 - Native CDP library integration (no subprocess overhead)
 - **Spectral processing:** `time_stretch`, `spectral_blur`, `modify_speed`, `pitch_shift`, `spectral_shift`, `spectral_stretch`, `filter_lowpass`, `filter_highpass`
 - **Envelope operations:** `dovetail`, `tremolo`, `attack`

{cycdp-0.1.1 → cycdp-0.1.2}/CMakeLists.txt

@@ -2,6 +2,7 @@ cmake_minimum_required(VERSION 3.15...3.31)
 project(${SKBUILD_PROJECT_NAME} VERSION ${SKBUILD_PROJECT_VERSION} LANGUAGES C)
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
 find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
 

{cycdp-0.1.1 → cycdp-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cycdp
-Version: 0.1.1
+Version: 0.1.2
 Summary: Cython bindings for the CDP audio processing library
 Keywords: audio,dsp,signal-processing,spectral,granular,cython,cdp
 Author-Email: Shakeeb Alireza <shakfu@users.noreply.github.com>
@@ -34,15 +34,68 @@ Description-Content-Type: text/markdown
 
 # cycdp
 
-Python bindings for the CDP (Composers Desktop Project) audio processing library.
+Python bindings for the [CDP8](https://github.com/ComposersDesktop/CDP8) (Composers Desktop Project, Release 8) audio processing library.
 
 ## Overview
 
-cycdp provides Python access to CDP's extensive audio processing algorithms. It uses Cython with memoryviews and the buffer protocol for zero-copy interoperability with numpy, `array.array`, and other buffer-compatible objects - **no numpy dependency required**.
+The [Composers Desktop Project](https://www.composersdesktop.com) (CDP) is a venerable suite of over 500 sound transformation programs developed since the late 1980s by Trevor Wishart, Richard Orton, and others. It occupies a unique niche in audio processing: where most tools focus on mixing, mastering, or standard effects, CDP specializes in deep spectral manipulation, granular synthesis, pitch-synchronous operations, waveset distortion, and other techniques rooted in the electroacoustic and computer music traditions.
+
+Historically, CDP programs are invoked as standalone command-line executables that read and write sound files, which makes integration into modern workflows cumbersome. **cycdp** solves this in two ways. First, a C library (`libcdp`) reimplements a curated subset of CDP's algorithms to operate directly on memory buffers. Second, a shim layer intercepts the file I/O calls inside original CDP algorithm code (the `sfsys` open/read/write/seek functions) and redirects them to memory buffers transparently, so those algorithms can run in-process without touching the filesystem. Both paths are exposed to Python via Cython bindings, giving you native-speed audio processing with a Pythonic API, zero-copy buffer interoperability, and no subprocess overhead.
+
+### Design principles
+
+- **Zero-copy interop.** Cython memoryviews and the buffer protocol mean data passes between Python and C without copying.
+- **No numpy dependency.** Operates on any object supporting the Python buffer protocol (`array.array`, `memoryview`, numpy arrays, etc.). Numpy is optional, not required.
+- **Functional API.** Most functions accept a buffer and return a new buffer, leaving the original unchanged. Low-level in-place alternatives are also available.
+- **Self-contained.** The C library is compiled into the extension; no external CDP installation is needed.
+
+## Features
+
+**Spectral Processing** -- Time stretching (preserving pitch), pitch shifting (preserving duration), spectral blur, shift, stretch, focus, hilite, fold, and noise cleaning.
+
+**Granular Synthesis** -- Classic brassage, freeze, grain clouds, grain time-extension, simple and multi-layer texture synthesis, wrappage, plus extended grain operations (reorder, rerhythm, reverse, timewarp, repitch, stereo positioning, omit, duplicate).
+
+**Pitch-Synchronous Operations (PSOW)** -- Time-stretching that preserves pitch via PSOLA, grain extraction and interpolation, and a hover effect for sustained pitched textures.
+
+**FOF Extraction and Synthesis** -- Extract pitch-synchronous grains (FOFs), build a grain bank, resynthesize at arbitrary pitch and duration, and repitch with optional formant preservation.
+
+**Morphing and Cross-Synthesis** -- Spectral morphing between two sounds, gliding morphs over time, and vocoder-style cross-synthesis.
+
+**Distortion** -- Waveset-based techniques: overload/saturation, reverse, fractal, shuffle, cut with decaying envelopes, marker-based interpolation, wavecycle repetition, half-wavecycle shifting, and progressive warp with sample folding.
+
+**Dynamics and EQ** -- Compressor, limiter, noise gate, parametric EQ, envelope follower, and envelope application.
+
+**Filters** -- Lowpass, highpass, bandpass, and notch (band-reject).
+
+**Effects** -- Reverb (FDN: 8 comb + 4 allpass), delay, chorus, flanger, ring modulation, bitcrush, tremolo, and attack reshaping.
+
+**Spatial Processing** -- Static and envelope-driven panning, stereo mirror and width control, spinning rotation with optional doppler, dual-rotation modulation, spatial tremolo, and phase-based stereo enhancement.
+
+**Playback and Time Manipulation** -- Zigzag, iterate, stutter, bounce, drunk-walk navigation, looping with crossfades, TDOLA time-stretching, waveset scrambling, splinter, and silence constriction.
+
+**Experimental / Chaos** -- Strange attractor (Lorenz), Brownian motion, crystal growth, fractal, Chirikov map, Cantor set, cascade, fracture, and tesselation transformations.
+
+**Analysis** -- Pitch tracking (YIN), formant analysis (LPC), and partial/harmonic extraction.
+
+**Synthesis** -- Waveform generation (sine, square, saw, ramp, triangle), white and pink noise, click/metronome tracks, and chord synthesis from MIDI notes.
+
+**Core Operations** -- Gain (linear and dB), normalization, phase inversion, peak detection, channel conversion (mono/stereo, split, merge, interleave), mixing, reverse, fade in/out, and concatenation.
+
+**File I/O** -- Read and write WAV files (float32, PCM16, PCM24).
 
 ## Installation
 
 ```bash
+pip install cycdp
+```
+
+If you prefer to build from source:
+
+```bash
+# clone the repository
+git clone https://github.com/shakfu/cycdp.git
+cd cycdp
+
 # Build and install in development mode
 make build
 
@@ -52,6 +105,40 @@ uv sync
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Process audio
+cycdp time-stretch input.wav --factor 2.0 -o stretched.wav
+cycdp reverb input.wav --decay-time 3.0 --mix 0.5
+cycdp pitch-shift input.wav --semitones 5 -o shifted.wav
+
+# Two-input operations
+cycdp morph voice.wav pad.wav --morph-end 0.7 -o morphed.wav
+cycdp mix2 track1.wav track2.wav -o mixed.wav
+
+# Synthesis (no input file)
+cycdp synth-wave --waveform saw --frequency 220 --duration 2.0 -o tone.wav
+cycdp synth-chord --midi-notes 60 64 67 --duration 1.0 -o chord.wav
+
+# Analysis (output to stdout)
+cycdp pitch input.wav
+cycdp pitch input.wav --format json
+cycdp formants input.wav --format csv -o formants.csv
+
+# Utilities
+cycdp info input.wav
+cycdp list                  # all commands grouped by category
+cycdp list spectral         # commands in one category
+cycdp version
+```
+
+Output is auto-normalized to 0.95 peak level by default. Use `--no-normalize` to disable, or `-n 0.8` to set a different target. When `-o` is omitted, output is written alongside the input as `<input_stem>_<command>.wav`.
+
+Also accessible as `python3 -m cycdp`.
+
+### Python API
+
 ```python
 import cycdp
 
@@ -414,10 +501,12 @@ These work with explicit Context and Buffer objects:
 ### Constants
 
 **Processing flags:**
+
 - `FLAG_NONE` - No processing flags
 - `FLAG_CLIP` - Clip output to [-1.0, 1.0]
 
 **Waveform types (for `synth_wave`):**
+
 - `WAVE_SINE` - Sine wave
 - `WAVE_SQUARE` - Square wave
 - `WAVE_SAW` - Sawtooth wave
@@ -425,6 +514,7 @@ These work with explicit Context and Buffer objects:
 - `WAVE_TRIANGLE` - Triangle wave
 
 **Scramble modes (for `scramble`):**
+
 - `SCRAMBLE_SHUFFLE` - Random shuffle
 - `SCRAMBLE_REVERSE` - Reverse order
 - `SCRAMBLE_SIZE_UP` - Sort by size (smallest first)
@@ -438,34 +528,63 @@ These work with explicit Context and Buffer objects:
 
 ## Architecture
 
+```text
+Python                  cycdp (high-level API)
+                            |
+Cython                  _core.pyx  (zero-copy buffer protocol)
+                            |
+              +-------------+-------------+
+              |                           |
+C         libcdp                      cdp_lib
+      (reimplemented             (shim-wrapped CDP8
+       algorithms)                  algorithms)
+          |                           |
+          +------ cdp_shim / cdp_io_redirect ------+
+                  (intercept sfsys I/O,
+                   redirect to memory buffers)
+                            |
+                        CDP8 sources
+                     (FFT, spectral core)
 ```
-cycdp/                          # Project root
-  src/cycdp/                    # Python package
+
+**libcdp** (`projects/libcdp/src/`) -- Core C library that reimplements CDP operations (buffer management, gain, channel ops, mixing, spatial, file I/O, utilities) to work directly on memory buffers.
+
+**cdp_lib** (`projects/libcdp/cdp_lib/`) -- Wrapper modules that call into original CDP8 algorithm code. Each category (spectral, granular, morph, distortion, etc.) has its own `.c`/`.h` pair. These rely on the shim layer to function without file I/O.
+
+**cdp_shim / cdp_io_redirect** (`projects/libcdp/cdp_lib/cdp_shim.*`, `cdp_io_redirect.*`) -- Intercept CDP's `sfsys` file operations (`sndopenEx`, `fgetfbufEx`, `fputfbufEx`, `sndseekEx`, etc.) and redirect them to memory buffers. This allows original CDP algorithms to run in-process without touching the filesystem, handling single and multi-input scenarios (e.g. morph, cross-synthesis) via slot-based buffer registration.
+
+**CDP8 sources** (`projects/cpd8/dev/`) -- Upstream CDP8 code (FFT routines, spectral processing core, header definitions) compiled in and accessed through the shim layer.
+
+### Directory layout
+
+```text
+cycdp/
+  src/cycdp/
     __init__.py                 # Public exports
+    __main__.py                 # Entry point for python3 -m cycdp
+    cli.py                      # CLI: registry, parser, handlers
     _core.pyx                   # Cython bindings
-    cdp_lib.pxd                 # Cython declarations
+    _core.pyi                   # Type stubs
+    cdp_lib.pxd                 # Cython declarations for C layer
   projects/
-    libcdp/                     # C library
+    libcdp/
       include/
-        cdp.h                   # Main public API
+        cdp.h                   # Public C API
         cdp_error.h             # Error codes
         cdp_types.h             # Type definitions
+      src/                      # Reimplemented core (buffer, gain, channel, ...)
       cdp_lib/
-        cdp_lib.h               # Library internal header
-        cdp_*.h                 # Category headers (filters, effects, etc.)
-      src/
-        context.c               # Context management
-        buffer.c                # Buffer management
-        gain.c                  # Gain/amplitude operations
-        io.c                    # File I/O
-        channel.c               # Channel operations
-        mix.c                   # Mixing operations
-        spatial.c               # Spatial/panning
-        utils.c                 # Utilities
-        error.c                 # Error handling
-    cpd8/                       # CDP8 sources (FFT, includes)
-      dev/
+        cdp_lib.h/.c            # Main library entry point
+        cdp_shim.h/.c           # Shim: sfsys replacement functions
+        cdp_io_redirect.h/.c    # I/O redirect: slot-based buffer routing
+        cdp_spectral.h/.c       # Spectral processing wrappers
+        cdp_granular.h/.c       # Granular synthesis wrappers
+        cdp_morph.h/.c          # Morphing wrappers
+        cdp_distort.h/.c        # Distortion wrappers
+        cdp_*.h/.c              # Other category wrappers
+    cpd8/dev/                   # Upstream CDP8 sources (FFT, includes)
   tests/                        # Python tests
+  demos/                        # Example scripts
   CMakeLists.txt                # Builds extension
 ```
 

{cycdp-0.1.1 → cycdp-0.1.2}/README.md

@@ -1,14 +1,67 @@
 # cycdp
 
-Python bindings for the CDP (Composers Desktop Project) audio processing library.
+Python bindings for the [CDP8](https://github.com/ComposersDesktop/CDP8) (Composers Desktop Project, Release 8) audio processing library.
 
 ## Overview
 
-cycdp provides Python access to CDP's extensive audio processing algorithms. It uses Cython with memoryviews and the buffer protocol for zero-copy interoperability with numpy, `array.array`, and other buffer-compatible objects - **no numpy dependency required**.
+The [Composers Desktop Project](https://www.composersdesktop.com) (CDP) is a venerable suite of over 500 sound transformation programs developed since the late 1980s by Trevor Wishart, Richard Orton, and others. It occupies a unique niche in audio processing: where most tools focus on mixing, mastering, or standard effects, CDP specializes in deep spectral manipulation, granular synthesis, pitch-synchronous operations, waveset distortion, and other techniques rooted in the electroacoustic and computer music traditions.
+
+Historically, CDP programs are invoked as standalone command-line executables that read and write sound files, which makes integration into modern workflows cumbersome. **cycdp** solves this in two ways. First, a C library (`libcdp`) reimplements a curated subset of CDP's algorithms to operate directly on memory buffers. Second, a shim layer intercepts the file I/O calls inside original CDP algorithm code (the `sfsys` open/read/write/seek functions) and redirects them to memory buffers transparently, so those algorithms can run in-process without touching the filesystem. Both paths are exposed to Python via Cython bindings, giving you native-speed audio processing with a Pythonic API, zero-copy buffer interoperability, and no subprocess overhead.
+
+### Design principles
+
+- **Zero-copy interop.** Cython memoryviews and the buffer protocol mean data passes between Python and C without copying.
+- **No numpy dependency.** Operates on any object supporting the Python buffer protocol (`array.array`, `memoryview`, numpy arrays, etc.). Numpy is optional, not required.
+- **Functional API.** Most functions accept a buffer and return a new buffer, leaving the original unchanged. Low-level in-place alternatives are also available.
+- **Self-contained.** The C library is compiled into the extension; no external CDP installation is needed.
+
+## Features
+
+**Spectral Processing** -- Time stretching (preserving pitch), pitch shifting (preserving duration), spectral blur, shift, stretch, focus, hilite, fold, and noise cleaning.
+
+**Granular Synthesis** -- Classic brassage, freeze, grain clouds, grain time-extension, simple and multi-layer texture synthesis, wrappage, plus extended grain operations (reorder, rerhythm, reverse, timewarp, repitch, stereo positioning, omit, duplicate).
+
+**Pitch-Synchronous Operations (PSOW)** -- Time-stretching that preserves pitch via PSOLA, grain extraction and interpolation, and a hover effect for sustained pitched textures.
+
+**FOF Extraction and Synthesis** -- Extract pitch-synchronous grains (FOFs), build a grain bank, resynthesize at arbitrary pitch and duration, and repitch with optional formant preservation.
+
+**Morphing and Cross-Synthesis** -- Spectral morphing between two sounds, gliding morphs over time, and vocoder-style cross-synthesis.
+
+**Distortion** -- Waveset-based techniques: overload/saturation, reverse, fractal, shuffle, cut with decaying envelopes, marker-based interpolation, wavecycle repetition, half-wavecycle shifting, and progressive warp with sample folding.
+
+**Dynamics and EQ** -- Compressor, limiter, noise gate, parametric EQ, envelope follower, and envelope application.
+
+**Filters** -- Lowpass, highpass, bandpass, and notch (band-reject).
+
+**Effects** -- Reverb (FDN: 8 comb + 4 allpass), delay, chorus, flanger, ring modulation, bitcrush, tremolo, and attack reshaping.
+
+**Spatial Processing** -- Static and envelope-driven panning, stereo mirror and width control, spinning rotation with optional doppler, dual-rotation modulation, spatial tremolo, and phase-based stereo enhancement.
+
+**Playback and Time Manipulation** -- Zigzag, iterate, stutter, bounce, drunk-walk navigation, looping with crossfades, TDOLA time-stretching, waveset scrambling, splinter, and silence constriction.
+
+**Experimental / Chaos** -- Strange attractor (Lorenz), Brownian motion, crystal growth, fractal, Chirikov map, Cantor set, cascade, fracture, and tesselation transformations.
+
+**Analysis** -- Pitch tracking (YIN), formant analysis (LPC), and partial/harmonic extraction.
+
+**Synthesis** -- Waveform generation (sine, square, saw, ramp, triangle), white and pink noise, click/metronome tracks, and chord synthesis from MIDI notes.
+
+**Core Operations** -- Gain (linear and dB), normalization, phase inversion, peak detection, channel conversion (mono/stereo, split, merge, interleave), mixing, reverse, fade in/out, and concatenation.
+
+**File I/O** -- Read and write WAV files (float32, PCM16, PCM24).
 
 ## Installation
 
 ```bash
+pip install cycdp
+```
+
+If you prefer to build from source:
+
+```bash
+# clone the repository
+git clone https://github.com/shakfu/cycdp.git
+cd cycdp
+
 # Build and install in development mode
 make build
 
@@ -18,6 +71,40 @@ uv sync
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Process audio
+cycdp time-stretch input.wav --factor 2.0 -o stretched.wav
+cycdp reverb input.wav --decay-time 3.0 --mix 0.5
+cycdp pitch-shift input.wav --semitones 5 -o shifted.wav
+
+# Two-input operations
+cycdp morph voice.wav pad.wav --morph-end 0.7 -o morphed.wav
+cycdp mix2 track1.wav track2.wav -o mixed.wav
+
+# Synthesis (no input file)
+cycdp synth-wave --waveform saw --frequency 220 --duration 2.0 -o tone.wav
+cycdp synth-chord --midi-notes 60 64 67 --duration 1.0 -o chord.wav
+
+# Analysis (output to stdout)
+cycdp pitch input.wav
+cycdp pitch input.wav --format json
+cycdp formants input.wav --format csv -o formants.csv
+
+# Utilities
+cycdp info input.wav
+cycdp list                  # all commands grouped by category
+cycdp list spectral         # commands in one category
+cycdp version
+```
+
+Output is auto-normalized to 0.95 peak level by default. Use `--no-normalize` to disable, or `-n 0.8` to set a different target. When `-o` is omitted, output is written alongside the input as `<input_stem>_<command>.wav`.
+
+Also accessible as `python3 -m cycdp`.
+
+### Python API
+
 ```python
 import cycdp
 
@@ -380,10 +467,12 @@ These work with explicit Context and Buffer objects:
 ### Constants
 
 **Processing flags:**
+
 - `FLAG_NONE` - No processing flags
 - `FLAG_CLIP` - Clip output to [-1.0, 1.0]
 
 **Waveform types (for `synth_wave`):**
+
 - `WAVE_SINE` - Sine wave
 - `WAVE_SQUARE` - Square wave
 - `WAVE_SAW` - Sawtooth wave
@@ -391,6 +480,7 @@ These work with explicit Context and Buffer objects:
 - `WAVE_TRIANGLE` - Triangle wave
 
 **Scramble modes (for `scramble`):**
+
 - `SCRAMBLE_SHUFFLE` - Random shuffle
 - `SCRAMBLE_REVERSE` - Reverse order
 - `SCRAMBLE_SIZE_UP` - Sort by size (smallest first)
@@ -404,34 +494,63 @@ These work with explicit Context and Buffer objects:
 
 ## Architecture
 
+```text
+Python                  cycdp (high-level API)
+                            |
+Cython                  _core.pyx  (zero-copy buffer protocol)
+                            |
+              +-------------+-------------+
+              |                           |
+C         libcdp                      cdp_lib
+      (reimplemented             (shim-wrapped CDP8
+       algorithms)                  algorithms)
+          |                           |
+          +------ cdp_shim / cdp_io_redirect ------+
+                  (intercept sfsys I/O,
+                   redirect to memory buffers)
+                            |
+                        CDP8 sources
+                     (FFT, spectral core)
 ```
-cycdp/                          # Project root
-  src/cycdp/                    # Python package
+
+**libcdp** (`projects/libcdp/src/`) -- Core C library that reimplements CDP operations (buffer management, gain, channel ops, mixing, spatial, file I/O, utilities) to work directly on memory buffers.
+
+**cdp_lib** (`projects/libcdp/cdp_lib/`) -- Wrapper modules that call into original CDP8 algorithm code. Each category (spectral, granular, morph, distortion, etc.) has its own `.c`/`.h` pair. These rely on the shim layer to function without file I/O.
+
+**cdp_shim / cdp_io_redirect** (`projects/libcdp/cdp_lib/cdp_shim.*`, `cdp_io_redirect.*`) -- Intercept CDP's `sfsys` file operations (`sndopenEx`, `fgetfbufEx`, `fputfbufEx`, `sndseekEx`, etc.) and redirect them to memory buffers. This allows original CDP algorithms to run in-process without touching the filesystem, handling single and multi-input scenarios (e.g. morph, cross-synthesis) via slot-based buffer registration.
+
+**CDP8 sources** (`projects/cpd8/dev/`) -- Upstream CDP8 code (FFT routines, spectral processing core, header definitions) compiled in and accessed through the shim layer.
+
+### Directory layout
+
+```text
+cycdp/
+  src/cycdp/
     __init__.py                 # Public exports
+    __main__.py                 # Entry point for python3 -m cycdp
+    cli.py                      # CLI: registry, parser, handlers
     _core.pyx                   # Cython bindings
-    cdp_lib.pxd                 # Cython declarations
+    _core.pyi                   # Type stubs
+    cdp_lib.pxd                 # Cython declarations for C layer
   projects/
-    libcdp/                     # C library
+    libcdp/
       include/
-        cdp.h                   # Main public API
+        cdp.h                   # Public C API
         cdp_error.h             # Error codes
         cdp_types.h             # Type definitions
+      src/                      # Reimplemented core (buffer, gain, channel, ...)
       cdp_lib/
-        cdp_lib.h               # Library internal header
-        cdp_*.h                 # Category headers (filters, effects, etc.)
-      src/
-        context.c               # Context management
-        buffer.c                # Buffer management
-        gain.c                  # Gain/amplitude operations
-        io.c                    # File I/O
-        channel.c               # Channel operations
-        mix.c                   # Mixing operations
-        spatial.c               # Spatial/panning
-        utils.c                 # Utilities
-        error.c                 # Error handling
-    cpd8/                       # CDP8 sources (FFT, includes)
-      dev/
+        cdp_lib.h/.c            # Main library entry point
+        cdp_shim.h/.c           # Shim: sfsys replacement functions
+        cdp_io_redirect.h/.c    # I/O redirect: slot-based buffer routing
+        cdp_spectral.h/.c       # Spectral processing wrappers
+        cdp_granular.h/.c       # Granular synthesis wrappers
+        cdp_morph.h/.c          # Morphing wrappers
+        cdp_distort.h/.c        # Distortion wrappers
+        cdp_*.h/.c              # Other category wrappers
+    cpd8/dev/                   # Upstream CDP8 sources (FFT, includes)
   tests/                        # Python tests
+  demos/                        # Example scripts
   CMakeLists.txt                # Builds extension
 ```