DiscordPHP-Voice Documentation

Runtime
in package

Application

FinalYes

Constants

CODEC_OPUS : mixed = 1
MEDIA_TYPE_AUDIO : mixed = 0
RESULT_SUCCESS : mixed = 0
FFI_TYPEDEF_PRELUDE : mixed = <<<'CDEF' typedef unsigned char uint8_t; typede...: Platform-specific typedefs prepended to FFI definitions.

Properties

$availabilityOverride : bool|null
$createDecryptorCallback : null|callable(): Array
$createSessionCallback : null|callable(Array): Array
$decryptorKeyRatchetCallback : null|callable(DecryptorHandle, KeyRatchetHandle): bool
$decryptorPassthroughCallback : null|callable(DecryptorHandle, bool): bool
$decryptWithDecryptorCallback : null|callable(DecryptorHandle, string): string|false
$ffi : FFI|null
$frameDecryptor : null|callable(string, int): false|string
$frameEncryptor : null|callable(string, int): Array
$keyPackageCallback : null|callable(SessionHandle): Array
$keyRatchetCallback : null|callable(SessionHandle, string): Array
$lastLoadError : string|null
$loaded : bool
$mlsCommitWelcomeBuilder : null|callable(string, int): Array
$processCommitCallback : null|callable(Array, string): Array
$processWelcomeCallback : null|callable(Array, string, array<string|int, mixed>): bool
$lastDestroyError : string|null

Methods

buildMlsCommitWelcome() : string|null: Builds an MLS commit+welcome from a proposals payload via the injected builder callback, or null. Production uses {@see buildMlsCommitWelcomeWithSession()} instead.
buildMlsCommitWelcomeWithSession() : string|null
configureCallbacks() : void
configureDecryptorKeyRatchet() : bool: Binds `$keyRatchet` as `$decryptor`'s key source.
configureDecryptorPassthrough() : bool: Toggles passthrough (no-op decryption) on `$decryptor`.
configureEncryptorKeyRatchet() : bool: Binds `$keyRatchet` as `$encryptor`'s key source.
configureEncryptorPassthrough() : bool: Toggles passthrough (no-op encryption) on `$encryptor`.
createDecryptor() : DecryptorHandle|null: Creates a libdave media {@see DecryptorHandle}, or null on failure.
createEncryptor() : EncryptorHandle|null: Creates a libdave media {@see EncryptorHandle}, or null on failure.
createSession() : SessionHandle|null: Creates a new libdave MLS session (optionally bound to `$authSessionId`), or null on failure.
decryptMediaFrame() : string|false|null: Decrypts one media frame. Returns the frame unchanged in passthrough; otherwise uses the injected decryptor callback, or null. Production uses {@see decryptWithDecryptor()} per handle instead.
decryptWithDecryptor() : string|false|null: Decrypts `$frame` with `$decryptor`; returns the plaintext, false on a decrypt failure, or null when unavailable.
destroyNativeHandle() : void: Calls libdave `$destroyMethod` on `$handle`, recording any error in {@see getLastDestroyError()}.
encryptMediaFrame() : string|null: Encrypts one media frame. Returns the frame unchanged in passthrough (`protocolVersion <= 0`); otherwise uses the injected encryptor callback, or null. Production uses {@see encryptWithEncryptor()} per handle instead.
encryptWithEncryptor() : string|null: Encrypts `$frame` for `$ssrc` (codec `$codec`) with `$encryptor`; returns the ciphertext, or null on failure.
getKeyRatchet() : KeyRatchetHandle|null: A {@see KeyRatchetHandle} for `$userId` derived from `$session`, or null.
getLastDestroyError() : string|null: The message from the most recent native-handle destroy failure, or null.
getLastLoadError() : string|null: The message from the most recent load/FFI failure, or null.
getMarshalledKeyPackage() : string|null: The serialised MLS key package for `$session`, or null.
getSessionProtocolVersion() : int: `$session`'s active protocol version, or 0 on failure.
initializeSession() : bool: Initialises `$session` for the given protocol version, group id and self user id.
isAvailable() : bool: Whether a working libdave FFI binding is loaded (honouring any `configureCallbacks()` availability override).
loadHeaderDefinitions() : string|null: Reads and preprocesses the dave.h C header into FFI-compatible declarations.
maxProtocolVersion() : int: The highest DAVE protocol version libdave reports support for, or 0 when unavailable.
processCommit() : array<string|int, mixed>|null: Feeds an MLS commit to `$session`; returns `['failed' => bool, 'ignored' => bool]`, or null on failure.
processWelcome() : bool
reset() : void: Unloads the FFI binding and clears every injected callback and cached error. Primarily for tests.
resetSession() : bool: Resets `$session` to its post-creation state.
setExternalSender() : bool: Installs the group's external-sender package on `$session`.
setSessionProtocolVersion() : bool: Sets `$session`'s active protocol version.
call() : mixed: Invokes libdave function `$method` on the FFI binding with `$arguments` (an indirection that keeps static analysers happy about the dynamic call).
load() : void: Loads the libdave shared library and its `dave.h` FFI definitions once, discovering the library under `.cache/libdave/` or `DISCORDPHP_DAVE_LIBRARY`.
makeBytePointer() : array{0: mixed, 1: int, 2: mixed}
makeOutputByteBuffer() : array{0: mixed, 1: mixed}
makeStringPointerArray() : array{0: mixed, 1: list}
takeOutputBytes() : string|null: Reads `$length` bytes from a libdave-allocated output buffer and frees it. Returns null when the buffer pointer is null.
deriveHeaderPath() : string|null: Derives the dave.h header path from a resolved library path.
ffi() : FFI|null: The loaded {@see \FFI} binding (loading it on first call), or null when libdave is unavailable.
isAbsolutePath() : bool: Whether `$path` is absolute (leading `/`, or a `C:\` / `C:/` drive prefix on Windows).
resolveDefaultLibraryPath() : string: Resolves the default library path by probing known locations.
resolveDefinitions() : string: Resolves FFI C definitions from the dave.h header file co-located with the resolved library. Throws if the header cannot be found or parsed.

CODEC_OPUS


    public
        mixed
    CODEC_OPUS
    = 1

MEDIA_TYPE_AUDIO


    public
        mixed
    MEDIA_TYPE_AUDIO
    = 0

RESULT_SUCCESS


    protected
        mixed
    RESULT_SUCCESS
    = 0

FFI_TYPEDEF_PRELUDE

Platform-specific typedefs prepended to FFI definitions.


    private
        mixed
    FFI_TYPEDEF_PRELUDE
    = <<<'CDEF'
typedef unsigned char uint8_t;
typedef unsigned short uint16_t;
typedef unsigned int uint32_t;
typedef unsigned long size_t;
typedef unsigned long long uint64_t;
typedef _Bool bool;
CDEF

PHP FFI::cdef() does not process C headers, so we provide these explicitly.

$availabilityOverride


        protected
        static    bool|null
    $availabilityOverride
     = null

$createDecryptorCallback


        protected
        static    null|callable(): Array
    $createDecryptorCallback
     = null

$createSessionCallback


        protected
        static    null|callable(Array): Array
    $createSessionCallback
     = null

$decryptorKeyRatchetCallback


        protected
        static    null|callable(DecryptorHandle, KeyRatchetHandle): bool
    $decryptorKeyRatchetCallback
     = null

$decryptorPassthroughCallback


        protected
        static    null|callable(DecryptorHandle, bool): bool
    $decryptorPassthroughCallback
     = null

$decryptWithDecryptorCallback


        protected
        static    null|callable(DecryptorHandle, string): string|false
    $decryptWithDecryptorCallback
     = null

$ffi


        protected
        static    FFI|null
    $ffi
     = null

$frameDecryptor


        protected
        static    null|callable(string, int): false|string
    $frameDecryptor
     = null

$frameEncryptor


        protected
        static    null|callable(string, int): Array
    $frameEncryptor
     = null

$keyPackageCallback


        protected
        static    null|callable(SessionHandle): Array
    $keyPackageCallback
     = null

$keyRatchetCallback


        protected
        static    null|callable(SessionHandle, string): Array
    $keyRatchetCallback
     = null

$lastLoadError


        protected
        static    string|null
    $lastLoadError
     = null

$loaded


        protected
        static    bool
    $loaded
     = false

$mlsCommitWelcomeBuilder


        protected
        static    null|callable(string, int): Array
    $mlsCommitWelcomeBuilder
     = null

$processCommitCallback


        protected
        static    null|callable(Array, string): Array
    $processCommitCallback
     = null

$processWelcomeCallback


        protected
        static    null|callable(Array, string, array<string|int, mixed>): bool
    $processWelcomeCallback
     = null

$lastDestroyError


        private
        static    string|null
    $lastDestroyError
     = null

buildMlsCommitWelcome()

Builds an MLS commit+welcome from a proposals payload via the injected builder callback, or null. Production uses {@see buildMlsCommitWelcomeWithSession()} instead.


    public
            static        buildMlsCommitWelcome(string $proposalsPayload, int $protocolVersion) : string|null

Parameters

$proposalsPayload : string
$protocolVersion : int

Return values

string|null

buildMlsCommitWelcomeWithSession()


    public
            static        buildMlsCommitWelcomeWithSession(SessionHandle $session, string $proposalsPayload, array<int, string> $recognizedUserIds) : string|null

Parameters

$session : SessionHandle
$proposalsPayload : string
$recognizedUserIds : array<int, string>

Return values

string|null

configureCallbacks()


    public
            static        configureCallbacks([null|callable(string, int): Array $frameEncryptor = null ][, null|callable(string, int): false|string $frameDecryptor = null ][, null|callable(string, int): Array $mlsCommitWelcomeBuilder = null ][, null|callable(Array, string): Array $processCommitCallback = null ][, null|callable(Array, string, array<string|int, mixed>): bool $processWelcomeCallback = null ][, null|callable(Array): Array $createSessionCallback = null ][, bool|null $availabilityOverride = null ][, null|callable(SessionHandle): Array $keyPackageCallback = null ][, null|callable(): Array $createDecryptorCallback = null ][, null|callable(SessionHandle, string): Array $keyRatchetCallback = null ][, null|callable(DecryptorHandle, bool): bool $decryptorPassthroughCallback = null ][, null|callable(DecryptorHandle, KeyRatchetHandle): bool $decryptorKeyRatchetCallback = null ][, null|callable(DecryptorHandle, string): string $decryptWithDecryptorCallback = null ]) : void

Parameters

$frameEncryptor : null|callable(string, int): Array = null
$frameDecryptor : null|callable(string, int): false|string = null
$mlsCommitWelcomeBuilder : null|callable(string, int): Array = null
$processCommitCallback : null|callable(Array, string): Array = null
$processWelcomeCallback : null|callable(Array, string, array<string|int, mixed>): bool = null
$createSessionCallback : null|callable(Array): Array = null
$availabilityOverride : bool|null = null
$keyPackageCallback : null|callable(SessionHandle): Array = null
$createDecryptorCallback : null|callable(): Array = null
$keyRatchetCallback : null|callable(SessionHandle, string): Array = null
$decryptorPassthroughCallback : null|callable(DecryptorHandle, bool): bool = null
$decryptorKeyRatchetCallback : null|callable(DecryptorHandle, KeyRatchetHandle): bool = null
$decryptWithDecryptorCallback : null|callable(DecryptorHandle, string): string = null

configureDecryptorKeyRatchet()

Binds `$keyRatchet` as `$decryptor`'s key source.


    public
            static        configureDecryptorKeyRatchet(DecryptorHandle $decryptor, KeyRatchetHandle $keyRatchet) : bool

Parameters

$decryptor : DecryptorHandle
$keyRatchet : KeyRatchetHandle

Return values

bool

configureDecryptorPassthrough()

Toggles passthrough (no-op decryption) on `$decryptor`.


    public
            static        configureDecryptorPassthrough(DecryptorHandle $decryptor, bool $passthroughMode) : bool

Parameters

$decryptor : DecryptorHandle
$passthroughMode : bool

Return values

bool

configureEncryptorKeyRatchet()

Binds `$keyRatchet` as `$encryptor`'s key source.


    public
            static        configureEncryptorKeyRatchet(EncryptorHandle $encryptor, KeyRatchetHandle $keyRatchet) : bool

Parameters

$encryptor : EncryptorHandle
$keyRatchet : KeyRatchetHandle

Return values

bool

configureEncryptorPassthrough()

Toggles passthrough (no-op encryption) on `$encryptor`.


    public
            static        configureEncryptorPassthrough(EncryptorHandle $encryptor, bool $passthroughMode) : bool

Parameters

$encryptor : EncryptorHandle
$passthroughMode : bool

Return values

bool

createDecryptor()

Creates a libdave media {@see DecryptorHandle}, or null on failure.


    public
            static        createDecryptor() : DecryptorHandle|null

Return values

DecryptorHandle|null

createEncryptor()

Creates a libdave media {@see EncryptorHandle}, or null on failure.


    public
            static        createEncryptor() : EncryptorHandle|null

Return values

EncryptorHandle|null

createSession()

Creates a new libdave MLS session (optionally bound to `$authSessionId`), or null on failure.


    public
            static        createSession([string|null $authSessionId = null ]) : SessionHandle|null

Parameters

$authSessionId : string|null = null

Return values

SessionHandle|null

decryptMediaFrame()

Decrypts one media frame. Returns the frame unchanged in passthrough; otherwise uses the injected decryptor callback, or null. Production uses {@see decryptWithDecryptor()} per handle instead.


    public
            static        decryptMediaFrame(string $frame, int $protocolVersion) : string|false|null

Parameters

$frame : string
$protocolVersion : int

Return values

string|false|null

decryptWithDecryptor()

Decrypts `$frame` with `$decryptor`; returns the plaintext, false on a decrypt failure, or null when unavailable.


    public
            static        decryptWithDecryptor(DecryptorHandle $decryptor, string $frame) : string|false|null

Parameters

$decryptor : DecryptorHandle
$frame : string

Return values

string|false|null

destroyNativeHandle()

Calls libdave `$destroyMethod` on `$handle`, recording any error in {@see getLastDestroyError()}.


    public
            static        destroyNativeHandle(mixed $handle, string $destroyMethod) : void

Parameters

$handle : mixed
$destroyMethod : string

encryptMediaFrame()

Encrypts one media frame. Returns the frame unchanged in passthrough (`protocolVersion <= 0`); otherwise uses the injected encryptor callback, or null. Production uses {@see encryptWithEncryptor()} per handle instead.


    public
            static        encryptMediaFrame(string $frame, int $protocolVersion) : string|null

Parameters

$frame : string
$protocolVersion : int

Return values

string|null

encryptWithEncryptor()

Encrypts `$frame` for `$ssrc` (codec `$codec`) with `$encryptor`; returns the ciphertext, or null on failure.


    public
            static        encryptWithEncryptor(EncryptorHandle $encryptor, string $frame, int $ssrc[, int $codec = self::CODEC_OPUS ]) : string|null

Parameters

$encryptor : EncryptorHandle
$frame : string
$ssrc : int
$codec : int = self::CODEC_OPUS

Return values

string|null

getKeyRatchet()

A {@see KeyRatchetHandle} for `$userId` derived from `$session`, or null.


    public
            static        getKeyRatchet(SessionHandle $session, string $userId) : KeyRatchetHandle|null

Parameters

$session : SessionHandle
$userId : string

Return values

KeyRatchetHandle|null

getLastDestroyError()

The message from the most recent native-handle destroy failure, or null.


    public
            static        getLastDestroyError() : string|null

Return values

string|null

getLastLoadError()

The message from the most recent load/FFI failure, or null.


    public
            static        getLastLoadError() : string|null

Return values

string|null

getMarshalledKeyPackage()

The serialised MLS key package for `$session`, or null.


    public
            static        getMarshalledKeyPackage(SessionHandle $session) : string|null

Parameters

$session : SessionHandle

Return values

string|null

getSessionProtocolVersion()

`$session`'s active protocol version, or 0 on failure.


    public
            static        getSessionProtocolVersion(SessionHandle $session) : int

Parameters

$session : SessionHandle

Return values

int

initializeSession()

Initialises `$session` for the given protocol version, group id and self user id.


    public
            static        initializeSession(SessionHandle $session, int $version, int $groupId, string $selfUserId) : bool

Parameters

$session : SessionHandle
$version : int
$groupId : int
$selfUserId : string

Return values

bool

isAvailable()

Whether a working libdave FFI binding is loaded (honouring any `configureCallbacks()` availability override).


    public
            static        isAvailable() : bool

Return values

bool

loadHeaderDefinitions()

Reads and preprocesses the dave.h C header into FFI-compatible declarations.


    public
            static        loadHeaderDefinitions(string $headerPath) : string|null

Handles: preprocessor directives, DAVE_EXPORT attribute, opaque-handle macro expansion, extern "C" blocks, and C doc comments.

Parameters

$headerPath : string

Return values

string|null

maxProtocolVersion()

The highest DAVE protocol version libdave reports support for, or 0 when unavailable.


    public
            static        maxProtocolVersion() : int

Return values

int

processCommit()

Feeds an MLS commit to `$session`; returns `['failed' => bool, 'ignored' => bool]`, or null on failure.


    public
            static        processCommit(SessionHandle $session, string $commit) : array<string|int, mixed>|null

Parameters

$session : SessionHandle
$commit : string

Return values

array<string|int, mixed>|null

processWelcome()


    public
            static        processWelcome(SessionHandle $session, string $welcome, array<int, string> $recognizedUserIds) : bool

Parameters

$session : SessionHandle
$welcome : string
$recognizedUserIds : array<int, string>

Return values

bool

reset()

Unloads the FFI binding and clears every injected callback and cached error. Primarily for tests.


    public
            static        reset() : void

resetSession()

Resets `$session` to its post-creation state.


    public
            static        resetSession(SessionHandle $session) : bool

Parameters

$session : SessionHandle

Return values

bool

setExternalSender()

Installs the group's external-sender package on `$session`.


    public
            static        setExternalSender(SessionHandle $session, string $externalSender) : bool

Parameters

$session : SessionHandle
$externalSender : string

Return values

bool

setSessionProtocolVersion()

Sets `$session`'s active protocol version.


    public
            static        setSessionProtocolVersion(SessionHandle $session, int $version) : bool

Parameters

$session : SessionHandle
$version : int

Return values

bool

call()

Invokes libdave function `$method` on the FFI binding with `$arguments` (an indirection that keeps static analysers happy about the dynamic call).


    protected
            static        call(FFI $ffi, string $method, mixed ...$arguments) : mixed

Parameters

$ffi : FFI
$method : string
$arguments : mixed

load()

Loads the libdave shared library and its `dave.h` FFI definitions once, discovering the library under `.cache/libdave/` or `DISCORDPHP_DAVE_LIBRARY`.


    protected
            static        load() : void

Failures are swallowed and surfaced via getLastLoadError().

makeBytePointer()


    protected
            static        makeBytePointer(string $bytes) : array{0: mixed, 1: int, 2: mixed}

Parameters

$bytes : string

Return values

array{0: mixed, 1: int, 2: mixed}

makeOutputByteBuffer()


    protected
            static        makeOutputByteBuffer() : array{0: mixed, 1: mixed}

Return values

array{0: mixed, 1: mixed}

makeStringPointerArray()


    protected
            static        makeStringPointerArray(array<int, string> $strings) : array{0: mixed, 1: list}

Parameters

$strings : array<int, string>

Return values

array{0: mixed, 1: list}

takeOutputBytes()

Reads `$length` bytes from a libdave-allocated output buffer and frees it. Returns null when the buffer pointer is null.


    protected
            static        takeOutputBytes(mixed $buffer, mixed $length) : string|null

Parameters

$buffer : mixed
$length : mixed

Return values

string|null

deriveHeaderPath()

Derives the dave.h header path from a resolved library path.


    private
            static        deriveHeaderPath(string $libraryPath) : string|null

Expected layout: Linux/macOS: {root}/.cache/libdave/lib/libdave.{so|dylib} Windows: {root}/.cache/libdave/bin/libdave.dll Header: {root}/.cache/libdave/include/dave/dave.h

Parameters

$libraryPath : string

Return values

string|null

ffi()

The loaded {@see \FFI} binding (loading it on first call), or null when libdave is unavailable.


    private
            static        ffi() : FFI|null

Return values

FFI|null

isAbsolutePath()

Whether `$path` is absolute (leading `/`, or a `C:\` / `C:/` drive prefix on Windows).


    private
            static        isAbsolutePath(string $path) : bool

Parameters

$path : string

Return values

bool

resolveDefaultLibraryPath()

Resolves the default library path by probing known locations.


    private
            static        resolveDefaultLibraryPath() : string

Probe order:

Package root (relative to DIR): .cache/libdave/lib/libdave.{ext}
Working directory: .cache/libdave/lib/libdave.{ext}

Return values

string

resolveDefinitions()

Resolves FFI C definitions from the dave.h header file co-located with the resolved library. Throws if the header cannot be found or parsed.


    private
            static        resolveDefinitions(string $libraryPath) : string

Parameters

$libraryPath : string

Return values

string

Runtime in package Application

Table of Contents

Constants

Properties

Methods

Constants

CODEC_OPUS

MEDIA_TYPE_AUDIO

RESULT_SUCCESS

FFI_TYPEDEF_PRELUDE

Properties

$availabilityOverride

$createDecryptorCallback

$createSessionCallback

$decryptorKeyRatchetCallback

$decryptorPassthroughCallback

$decryptWithDecryptorCallback

$ffi

$frameDecryptor

$frameEncryptor

$keyPackageCallback

$keyRatchetCallback

$lastLoadError

$loaded

$mlsCommitWelcomeBuilder

$processCommitCallback

$processWelcomeCallback

$lastDestroyError

Methods

buildMlsCommitWelcome()

Parameters

Return values

buildMlsCommitWelcomeWithSession()

Parameters

Return values

configureCallbacks()

Parameters

configureDecryptorKeyRatchet()

Parameters

Return values

configureDecryptorPassthrough()

Parameters

Return values

configureEncryptorKeyRatchet()

Parameters

Return values

configureEncryptorPassthrough()

Parameters

Return values

createDecryptor()

Return values

createEncryptor()

Return values

createSession()

Parameters

Return values

decryptMediaFrame()

Parameters

Return values

decryptWithDecryptor()

Parameters

Return values

destroyNativeHandle()

Parameters

encryptMediaFrame()

Parameters

Return values

encryptWithEncryptor()

Parameters

Return values

getKeyRatchet()

Parameters

Return values

getLastDestroyError()

Return values

getLastLoadError()

Return values

getMarshalledKeyPackage()

Parameters

Return values

Runtime
in package

Application