Link Search Menu Expand Document
⭐️ 1.8k 🌞 🌚

danog\MadelineProto\EventHandler\Call

Back to index

Author: Daniil Gentili daniil@daniil.it

Common interface implemented by every call type: one-to-one {@see Calls\PrivateCall} calls, and the

multi-party {@see Calls\GroupCall} (video chats, livestreams) and {@see Calls\ConferenceCall} (end-to-end encrypted conference) calls, which additionally implement {@see MultiCall}.

It covers the whole surface shared by all call types, so code can drive any call uniformly:

  • the lifecycle ({@see self::join()}, {@see self::discard()}, {@see self::isJoined()}, {@see self::getCallState()}),
  • who is in the call ({@see self::getParticipants()}) and, for end-to-end encrypted calls, the key verification emojis ({@see self::getVisualization()}),
  • the playlist/DJ playback controls and the mute controls,
  • screen sharing ({@see self::enablePresentation()} and friends) and
  • recording ({@see self::setOutput()}).

Every playlist control takes a {@see MediaDestination} selecting the stream it acts on: the main camera+mic stream (default) or a separate presentation (screen-share) stream, which is started on first use.

Method list:

Methods:

join(bool $muted = false): static

Join the call: accept an incoming one-to-one call, or join a multi-party call.

Parameters:

  • $muted: bool Whether to join with our own audio muted.

discard(): static

Discard the call: hang up a one-to-one call, or end a multi-party call for every participant (see {@see MultiCall::leave()} to leave one without ending it).

isJoined(): bool

Whether we are currently in the call: a one-to-one call that is running, or a multi-party call we joined and did not leave.

getCallState(): \danog\MadelineProto\VoIP\CallState|\danog\MadelineProto\GroupCall\GroupCallState

The state of the call: a {@see CallState} for a one-to-one call, a {@see GroupCallState} for a multi-party call.

See also:

getParticipants(): array<int, mixed>

The participants currently known to be in the call, keyed by their bot API id.

The element type is call-type specific, so the concrete class documents it: the other party’s
{@see \danog\MadelineProto\VoIP\MediaState} for a one-to-one call, a
{@see \danog\MadelineProto\GroupCall\Participant} for a group call, the chain state for a conference.

getParticipant(mixed $participant): mixed

A participant of the call by their id, username or peer, or null if they are not in it; the element type is the same as {@see self::getParticipants()}’s.

Parameters:

  • $participant: mixed

getVisualization(): (list<string>|null)

The key verification emojis of an end-to-end encrypted call (a one-to-one call or a conference), which every participant can compare to make sure nobody is in the middle.

Returns null until the key is established (and, for a conference, every participant has taken
part in the verification), and always for a call that is not end-to-end encrypted (a video chat
or livestream).

play(\danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream $file, \danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Play a file, transmitting its audio and, if it carries a transmittable one, its video.

A WebM/Matroska file with VP8, VP9, H.264 or AV1 video has its video transmitted too; any other
file (or a raw audio stream) is played as audio only. Frames are demuxed in pure PHP and sent
as-is where possible, so no transcoding (and thus no FFI extension) is required for pre-encoded
WebM/OGG-OPUS input. $dest selects the camera or the presentation (screencast) stream.

Parameters:

  • $file: \danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream
  • $dest: \danog\MadelineProto\MediaDestination

See also:

playBlocking(\danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream $file, \danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Play a file like {@see self::play()}, but block until it has finished playing if a stream was passed.

Parameters:

  • $file: \danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream
  • $dest: \danog\MadelineProto\MediaDestination

See also:

then(\danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream $file, \danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Add a file to the playlist, to be played once the current one finishes.

Parameters:

  • $file: \danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream
  • $dest: \danog\MadelineProto\MediaDestination

See also:

playOnHold(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera, \danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream ...$files): static

Set the files to play, on loop, while the given stream’s main playlist is empty.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination
  • ...$files: \danog\MadelineProto\LocalFile|\danog\MadelineProto\RemoteUrl|\Amp\ByteStream\ReadableStream

See also:

skip(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Skip to the next file in the playlist.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination

See also:

stop(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Stop playing all files, clearing the main and the hold playlist.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination

See also:

pause(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Pause playback of the current file.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination

See also:

isPaused(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): bool

Whether playback of the current file is paused.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination

See also:

resume(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): static

Resume playback of the current file.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination

See also:

getCurrent(\danog\MadelineProto\MediaDestination $dest = \danog\MadelineProto\MediaDestination::Camera): \danog\MadelineProto\RemoteUrl|\danog\MadelineProto\LocalFile|string|null

The file or stream currently being played, if any.

Returns a string with the object ID of the stream if a stream is playing, otherwise the related
{@see LocalFile} or {@see RemoteUrl}.

Parameters:

  • $dest: \danog\MadelineProto\MediaDestination

See also:

setMuted(bool $muted = true): static

Mute or unmute our own outgoing audio.

Parameters:

  • $muted: bool

isMuted(): bool

Whether our own outgoing audio is muted.

enablePresentation(): static

Start sharing a screen: bring up the presentation (screencast) stream, so that files played on {@see MediaDestination::Presentation} are transmitted as a screen-share. Idempotent, and done
automatically by the first playback on the presentation stream.

disablePresentation(): static

Stop sharing the screen, dropping the presentation playlist.

isSharingScreen(): bool

Whether a screen-share is currently being transmitted.

setOutput(\danog\MadelineProto\LocalFile|\danog\MadelineProto\LocalDirectory|\Amp\ByteStream\WritableStream $file, mixed $participant = NULL, ?\danog\MadelineProto\RecordingFormat $format = NULL): static

Record the incoming media of the call.

A recording holds everything a participant sends: their microphone audio, their camera video
and their screen share (a second video track), whichever of them are on. A participant may turn
any of these on or off at any time, in any combination; since a Matroska file’s track list is
fixed in its header, every such change closes the current file and continues in a new one, so
a recording is a numbered series of files, each named after the streams it holds: <stem>.0_audio.mkv,
<stem>.1_audio,video.mkv, <stem>.2_audio,video,screen.mkv, … (audio, video and screen,
joined by commas, in that order).

$file is where to record to:

  • in a one-to-one call, a {@see LocalFile} name.mkv records the other party as name.<n>_<streams>.mkv,
    and a {@see LocalDirectory} as <dir>/<n>_<streams>.mkv;
  • in a multi-party call only a {@see LocalDirectory} is accepted (stream-mode livestreams aside):
    every participant that transmits something (including ones that start later) is recorded as
    <dir>/<peerId>.<n>_<streams>.mkv, or only the one given as $participant (a user id, username
    or peer) if any. Our own media is never recorded;
  • a {@see WritableStream} (one-to-one calls only) gets a single file that cannot roll over, so it
    keeps its initial tracks.

A {@see RecordingFormat::Webm} or {@see RecordingFormat::Mkv} target muxes the media into a
Matroska file in pure PHP: the frames are stored as-is, so the video tracks are whatever codec the
peer sends (VP8/VP9/H.264/H.265/AV1) and the audio is OPUS. {@see RecordingFormat::Opus} writes an
audio-only OGG OPUS stream, and is supported by one-to-one calls only. When $format is null it
is autodetected from the extension of $file if a {@see LocalFile} was passed; a raw stream,
whose extension is unknown, defaults to OGG OPUS in a one-to-one call and to Matroska otherwise.

Parameters:

  • $file: \danog\MadelineProto\LocalFile|\danog\MadelineProto\LocalDirectory|\Amp\ByteStream\WritableStream
  • $participant: mixed
  • $format: ?\danog\MadelineProto\RecordingFormat

See also:

Generated by danog/phpdoc