Metadata-Version: 2.4
Name: voicegram
Version: 0.0.1
Summary: Lightweight Python library that turns any audio file into a Telegram voice note (.ogg/Opus) — and back.
Project-URL: Homepage, https://github.com/frymex/voicegram
Project-URL: Changelog, https://github.com/frymex/voicegram/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/frymex/voicegram/issues
Author-email: Nikita Protect <t_frymex@proton.me>
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.9
Requires-Dist: opuslib>=3.0
Requires-Dist: pydub>=0.25
Description-Content-Type: text/markdown

# voicegram

> Lightweight Python **library** that converts any audio file into a Telegram‑ready voice note (OGG/Opus) — and back again.

[![PyPI](https://img.shields.io/pypi/v/voicegram.svg)](https://pypi.org/project/voicegram/)
[![CI](https://github.com/frymex/voicegram/actions/workflows/ci.yml/badge.svg)](https://github.com/frymex/voicegram/actions)

---

## Why?

Telegram expects voice messages in a fairly specific format: Opus‑encoded OGG, 48 kHz, mono/stereo. Configuring `ffmpeg` every time is tedious. **voicegram** wraps those flags in a minimal API, so your code can simply read:

```python
from voicegram import VoiceConverter, mp3_to_opus

vc = VoiceConverter()
vc.mp3_to_opus("song.mp3", "note.ogg")  # library call

# or one‑liner helper
mp3_to_opus("song.mp3")                   # -> song.ogg
```

No boilerplate, no codec guessing.

---

## Installation

```bash
pip install voicegram  # Python ≥ 3.9 and ffmpeg ≥ 4.3 required
```

---

## Quick start

```python
from voicegram import VoiceConverter

vc = VoiceConverter()

# Convert anything ffmpeg can read to Telegram voice note
vc.mp3_to_opus("voice.wav")          # → voice.ogg

# Convert it back to MP3 (e.g. for sharing elsewhere)
vc.opus_to_mp3("voice.ogg")          # → voice.mp3
```

---

## API reference

| Method | Purpose |
|--------|---------|
| `VoiceConverter.mp3_to_opus(src, dst=None, bitrate="96k", vbr=True)` | Convert arbitrary audio to Opus‑encoded OGG. |
| `VoiceConverter.opus_to_mp3(src, dst=None, quality="2")` | Convert OGG/Opus back to MP3. |

Additionally, top‑level helpers `mp3_to_opus()` and `opus_to_mp3()` proxy to a shared converter instance.

Full docs live in the [wiki](https://github.com/yourname/voicegram/wiki).

---

## Development

```bash
git clone https://github.com/yourname/voicegram
cd voicegram
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]      # pytest, black, mypy, pre‑commit …
pytest -q
```

### Releasing

1. Bump version in `pyproject.toml`.
2. `git tag vX.Y.Z && git push --tags`.
3. GitHub Actions publishes wheels to PyPI via Trusted Publisher.

---

## License

MIT — see [LICENSE](LICENSE) for details.
