Metadata-Version: 2.4
Name: discord-native-voice
Version: 0.1.1
Summary: Voice, video, and stream transport extension for discord.py-self
Author-email: Dolfies <me@dolfi.es>
License: The MIT License (MIT)
        
        Copyright (c) 2026-present Dolfies
        
        Permission is hereby granted, free of charge, to any person obtaining a
        copy of this software and associated documentation files (the "Software"),
        to deal in the Software without restriction, including without limitation
        the rights to use, copy, modify, merge, publish, distribute, sublicense,
        and/or sell copies of the Software, and to permit persons to whom the
        Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
        OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
Project-URL: Documentation, https://discord-native-voice.readthedocs.io/en/latest/
Project-URL: Issue tracker, https://github.com/dolfies/discord.py-self/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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: Programming Language :: Rust
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: discord.py-self>=2.2.0
Provides-Extra: dev
Requires-Dist: ruff==0.12.0; extra == "dev"
Dynamic: license-file

# discord-native-voice

A native voice extension for
[discord.py-self](https://github.com/dolfies/discord.py-self).

This package plugs into discord.py-self's normal voice connection flow and adds
voice receive, video, and Go Live stream support. It is meant to feel like a
drop-in replacement for the existing `VoiceClient`.

> [!IMPORTANT]
> This project is still under active development and may have issues.
>
> Currently, it is only compatible with discord.py-self.
> discord.py is not supported, but contributions towards changing this are welcome.

## Key Features

- Native voice send and receive
- Video send and receive for all Discord video codecs: AV1, H265, H264, VP8, and VP9
- Go Live stream creation, watching, sending, and receiving
- Media sources for FFmpeg files, desktop capture, raw audio, and raw video
- Media sinks for callbacks, queues, WAV output, FFmpeg output, and muxed audio/video recordings
- Codec advertisement based on local FFmpeg support
- RTX/NACK support for video packet recovery
- Video simulcast support
- End-to-end encryption support with DAVE
- Compatible with nearly all existing voice sinks

## Installing

**Python 3.10 or higher is required.**

Install discord.py-self first, then install this extension:

```sh
# Linux/macOS
python3 -m pip install -U discord.py-self <todo>

# Windows
py -3 -m pip install -U discord.py-self <todo>
```

Note that [PyNaCl](https://pypi.org/project/PyNaCl/) is not required when using this extension.

A Rust toolchain is required when building from source. FFmpeg is also
recommended, since the built-in file, desktop, and recording helpers use it.

For development tools:

```sh
python3 -m pip install -U .[dev]
```

## Quick Example

> [!NOTE]
> In the future, discord.py-self will automatically prioritize this extension's voice implementation when installed.

Connect with the native voice client:

```python
from discord.ext.native_voice import VoiceClient

voice = await channel.connect(cls=VoiceClient, self_video=True)
```

Play a media file with audio and video:

```python
from discord.ext.native_voice import FFmpegMediaSource, VoiceClient

voice = await channel.connect(cls=VoiceClient, self_video=True)

source = FFmpegMediaSource.from_file(
    'clip.mp4',
    'H264',
    width=1280,
    height=720,
    fps=30,
    bitrate=4_000_000,
)

voice.play(source)
```

Receive media with a callback:

```python
from discord.ext.native_voice import MediaPacket, VoiceClient

voice = await channel.connect(cls=VoiceClient)

def on_packet(packet: MediaPacket) -> None:
    print(packet.media_type, packet.codec, packet.user_id)

voice.listen(on_packet)
```

### Go Live Streams

Streams use a separate `StreamClient`, created from an existing native voice
connection.

```python
from discord.ext.native_voice import FFmpegMediaSource, StreamClient, VoiceClient

voice = await channel.connect(cls=VoiceClient)
stream = await voice.create_stream(cls=StreamClient)

# Simplified example, reality is slightly more complicated
source = FFmpegMediaSource.from_desktop(
    'H264',
    width=1920,
    height=1080,
    fps=30,
    bitrate=6_000_000,
)

stream.play(source)
```

To watch another user's stream:

```python
stream = voice.streams[0]
stream_client = await stream.watch(cls=StreamClient)
```

### Configuration

Options that affect Discord's voice negotiation should be set before connecting.
Use `with_config()` to create a configured client class:

```python
from discord.ext.native_voice import VoiceClient

ConfiguredVoiceClient = VoiceClient.with_config(
    rtx=False,
    udp_qos=True,
    enable_debug_stats=True,
)

voice = await channel.connect(cls=ConfiguredVoiceClient, self_video=True)
```

## Media Helpers

The extension includes source and sink helpers for common media tasks:

- `FFmpegMediaSource` and `FFmpegVideoSource` for files, pipes, and desktop capture.
- `PCMMediaSource`, `AudioFrameSource`, and `VideoFrameSource` for already produced audio or video.
- `QueueSink` and `AsyncQueueSink` for application-managed receive loops.
- `WaveSink`, `MixedWaveSink`, `FFmpegSink`, and `FFmpegMuxSink` for recording.
- `MultiSink`, `PerUserSink`, and filter sinks for routing packets.

For advanced integrations, received media is exposed as `MediaPacket` objects
with RTP metadata and parsed RTP extensions.

## Docs

Docs are available at https://discord-native-voice.readthedocs.io/en/latest/index.html. Credits to [discord.py](https://github.com/Rapptz/discord.py) for the theme.

## Issues

For now, issues should be opened under this repository. Eventually, they will be migrated to the discord.py-self repository.

## Links

- [discord.py-self](https://github.com/dolfies/discord.py-self)
