Metadata-Version: 2.4
Name: phonotensor
Version: 0.2.2
Summary: Audio as mathematical data — collect, operate, transform, and export.
Author: Ayush Jha
License: Copyright (c) 2026 Emberflock Labs (Owner: Ayush Jha). All rights reserved.
Project-URL: Homepage, https://github.com/invictus-source/phonotensor
Project-URL: Documentation, https://github.com/invictus-source/phonotensor/blob/main/README.md
Project-URL: Bug Tracker, https://github.com/invictus-source/phonotensor/issues
Keywords: audio,dsp,tensor,numpy,sound
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sounddevice>=0.5
Requires-Dist: numpy>=1.26
Requires-Dist: soundfile>=0.12
Requires-Dist: scipy>=1.12
Provides-Extra: mp3
Requires-Dist: pydub>=0.25; extra == "mp3"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: scipy-stubs; extra == "dev"
Dynamic: license-file

# 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`:

```bash
pip install phonotensor
```

*(Optional)* For MP3 support:
```bash
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:

```python
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.

