Phonotensor

Audio as mathematical data — collect, operate, transform, and export.

Phonotensor is a robust, well-typed Python library that treats audio not just as files, but as structured, manipulatable mathematical tensors. It provides a simple, fluent API for audio collection, mathematical manipulation (DSP), and deterministic playback with state-of-the-art OS-level permission management.

Features

• Deterministic Recording & Playback: Cross-platform stream management via sounddevice and portaudio.
• Comprehensive Permission Model: Safe hardware and filesystem verification before resource acquisition.
• Fluent DSP Operators: Mix, concatenate, fade, filter, and modify volumes mathematically.
• Robustness: 100% strict type coverage and exhaustive automated testing.

Installation

Install Phonotensor via pip:

pip install phonotensor

(Optional) For MP3 support:

pip install phonotensor[mp3]

Quickstart

Here is a simple example to record 3 seconds from your microphone, generate a sine wave, mix them together, and play the result:

import numpy as np
from phonotensor import MicrophoneSource, AudioTensor, AudioPlayer, ops, fmt

# Initialize your microphone securely
mic = MicrophoneSource(sample_rate=44100, channels=1)

print("Recording for 3 seconds...")
audio = mic.record(duration=3.0)

# Generate a 440Hz sine wave tone
frequency = 440
tone = AudioTensor.from_function(
    lambda t: 0.3 * np.sin(2 * np.pi * frequency * t),
    duration=3.0,
    sample_rate=44100,
)

# Math operations: Mixing the microphone signal with the tone
mixed = ops.mix([audio, tone], weights=[0.7, 0.3])

# Summarize the audio context
print(fmt.describe(mixed))

# Play it back
player = AudioPlayer()
player.play(mixed)

License

Copyright (c) 2026 Emberflock Labs (Owner: Ayush Jha). All rights reserved.