Troubleshooting & release notes

Audio devices and permissions

Recording and playback need a local audio device, system drivers, and permission to use them. A hosted notebook, container, or Vercel function normally cannot access your computer’s microphone. File processing and numerical operations do not need an audio device.

On Windows, allow microphone access for desktop apps. On macOS, allow your terminal or IDE in microphone privacy settings. On Linux, check the audio service and access to /dev/snd. PortAudio is the implemented backend; platform-specific backend labels do not imply separate native engines.

skip_permission_check=True skips the package’s preflight checks. It does not bypass OS permissions or make an unavailable device work. Permission probes are best-effort, so successful checks do not guarantee a stream can open.

from phonotensor import MicrophoneSource, PhonotensorError

try:
    mic = MicrophoneSource(sample_rate=44100, channels=1)
    recording = mic.record(duration=1.0)
except (PhonotensorError, OSError) as error:
    print(f"Audio setup needs attention: {error}")

Understand errors

ConfigurationError covers incompatible tensor sample rates or channels in operations that explicitly check them. Invalid dimensions, frequencies, or durations may raise ValueError. File reads may raise FileNotFoundError; permission failures have FilePermissionError, DevicePermissionError, and MicrophonePermissionError variants.

Not every dependency error is wrapped in PhonotensorError. Codec and backend errors may propagate from soundfile, sounddevice, or the operating system. Inspect the original message before changing your setup.

Known behavior in 0.2.2

AudioCollector is deprecated. Use MicrophoneSource and AudioPlayer for new code. AudioPlayer’s blocking=False option is not asynchronous in this release.

The pink_noise() implementation sums independent Gaussian noise arrays and normalizes them. It does not implement a verified 1/f spectrum; do not rely on it for calibrated pink-noise testing.

Avoid empty tensors in reductions such as peak() and normalize(). Use positive fade durations of at least one sample, especially with fade_out(). Pitch operations need enough input samples for their 2048-sample analysis window.

The published distribution is version 0.2.2, while its internal version string and the checked GitHub project metadata say 0.2.1. Use importlib.metadata.version('phonotensor') to identify the installed distribution.

Documentation sources

Signatures were extracted from the PyPI 0.2.2 wheel. Python source syntax was compared against GitHub commit 2565e4c and matched. Descriptions document the implementation, including limitations that are not explained in the repository README.

The GitHub repository and PyPI currently carry different license declarations. Check with Emberflock Labs if you need clarification on licensing. These pages do not resolve that discrepancy.