Metadata-Version: 2.5
Name: uploadkit-audio
Version: 0.1.0
Summary: Audio validators, policies, and metadata for UploadKit
Project-URL: Homepage, https://github.com/uploadkit/uploadkit-audio
Project-URL: Repository, https://github.com/uploadkit/uploadkit-audio
Author: UploadKit
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: audio,mutagen,uploadkit,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mutagen>=1.47
Requires-Dist: uploadkit>=0.2.0
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: uploadkit-testing>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# uploadkit-audio

[![CI](https://github.com/uploadkit/uploadkit-audio/actions/workflows/ci.yml/badge.svg)](https://github.com/uploadkit/uploadkit-audio/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-81%25-brightgreen)](https://github.com/uploadkit/uploadkit-audio/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)

Audio validators, policies, and metadata for UploadKit.

## What problem does this solve?

Codec, duration, and structural checks for audio uploads that plug into
`UploadPolicy.validators` without modifying UploadKit Core.

## When to use it

Use for MP3, WAV, FLAC, OGG/Opus, M4A/AAC, and WebM audio uploads.

## When not to use it

- Do not transcode, normalize, or generate waveforms here.
- Do not put generic MIME/filename checks here (see `uploadkit-security`).

## Installation

Requires **Python 3.10+**.

```bash
pip install uploadkit-audio
```

## Quick Start

```python
from uploadkit import Uploader
from uploadkit_audio import AudioPolicy

uploader = Uploader(
    AudioPolicy(max_duration_sec=600, allowed_codecs=frozenset({"mp3", "wav"})),
    storage=my_storage,
)
```

## Public API

| Symbol | Kind |
|--------|------|
| `AudioPolicy` | Public |
| `AudioMetadata` / `inspect_audio` | Public |
| `AudioStructureValidator` / `AudioCodecValidator` / `AudioLimitsValidator` | Public |
| `default_audio_validators` / `default_async_audio_validators` | Public |
| Async validator equivalents | Public |

## Coverage

The coverage badge is a **measured** total from
`coverage report --include='src/*'`, not an aspirational 100%. CI enforces
`--fail-under=80`.

Most of the gap is defensive and format-variant code in `metadata.py`
(non-WAV codecs, mutagen edge cases). Validators and policies are largely
covered. Unlike Core / framework adapters, this package does not claim 100%
yet — fixtures for those branches are welcome.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
