commonfate

Common Fate is a Python library that implements the Common Fate Transform (CFT) and Common Fate Model (CFM) for audio source separation. It provides tools to decompose audio signals into distinct time-varying harmonic sources based on their modulation profiles, enabling the separation of unison sources like multiple instruments or voices playing the same note.

Key Features

• Common Fate Transform — Converts a complex spectrogram into a tensor representation via patch-based 2D Fourier transforms, revealing spectral and temporal modulation textures.
• Common Fate Model — Uses an adapted PARAFAC/CANDECOMP factorization to decompose the CFT tensor into components representing individual sources with shared modulation characteristics.
• Audio Decomposition Wrapper — Includes a high-level function to process audio signals end-to-end, applying the CFT, fitting the CFM, and synthesizing separated components via Wiener or soft mask filtering.
• Optimized Computation — Leverages Einstein notation (via NumPy's einsum) and optionally integrates opt_einsum for accelerated tensor operations on large datasets.
• Flexible API — Offers both low-level transform/model functions and convenient utilities for audio I/O integration (e.g., with PySoundFile).

Philosophy

The project emphasizes a mathematically grounded approach to source separation, focusing on the "common fate" principle where sources with similar modulation profiles are grouped, enabling effective separation of unison audio mixtures without relying on deep learning.