Link Search Menu Expand Document
⭐️ 1.8k 🌞 🌚

danog\MadelineProto\EventHandler\MultiCall

Back to index

Author: Daniil Gentili daniil@daniil.it

Common interface for the multi-party call types — {@see Calls\GroupCall} (video chats, livestreams),

{@see Calls\LiveStory} (live stories) and {@see Calls\ConferenceCall} (end-to-end encrypted conference calls) — on top of the surface every call shares ({@see Call}).

It covers what a call with more than two participants adds over a one-to-one {@see Calls\PrivateCall} call: leaving without ending it for everyone else, managing who is in it (inviting, invite links, removing participants), its title and settings, and messaging its participants. What only some call types offer (server-side recording, scheduling, raising a hand, moderating messages, donations) lives on the concrete classes: {@see Calls\AbstractGroupCall} for everything a video chat and a live story share, {@see Calls\GroupCall} and {@see Calls\LiveStory} for their own.

Method list:

Methods:

leave(): static

Leave the call, keeping it running for the other participants (unlike {@see Call::discard()}, which ends it).

setTitle(string $title): static

Change the title of the call.

Parameters:

  • $title: string

invite(mixed ...$users): static

Invite users to the call.

Parameters:

  • ...$users: mixed The users to invite (user ids, usernames or peers).

exportInvite(bool $canSelfUnmute = false): string

Export an invite link to the call.

Parameters:

  • $canSelfUnmute: bool Whether users joining with this link may speak without asking; ignored where the call has no such distinction.

removeParticipant(mixed ...$participants): static

Remove participants from the call.

Parameters:

  • ...$participants: mixed The participants to remove (user ids, usernames or peers).

sendMessage(string $message, (\danog\MadelineProto\ParseMode|null) $parseMode = NULL, (int|null) $paidStars = NULL, mixed $sendAs = NULL): static

Send an in-call message » to the participants of the call, shown as an overlay by their clients (there is no chat history).

Parameters:

  • $message: string The text; markup in $parseMode is converted to entities.
  • $parseMode: (\danog\MadelineProto\ParseMode|null) Whether to parse HTML or Markdown markup in the text.
  • $paidStars: (int|null) Live stories only: Telegram Stars to donate with the message (at least the story’s minimum, see {@see Calls\LiveStory::setPaidMessagesStars()}).
  • $sendAs: mixed Live stories only: the peer to send the message as.

See also:

sendReaction(string $emoji, (int|null) $customEmojiId = NULL): static

Send an in-call reaction »: a single emoji, or a custom emoji (with the fallback emoji as $emoji).

Parameters:

  • $emoji: string The emoji.
  • $customEmojiId: (int|null) The document id of a custom emoji to send instead, $emoji being its fallback.

setMessagesEnabled(bool $enabled): static

Enable or disable in-call messages (admins only).

Parameters:

  • $enabled: bool

muteParticipant(mixed $participant, bool $muted = true): static

Mute or unmute a participant (admins only), or, for a non-admin, mute a participant only for ourselves. A participant muted by an admin may not unmute themselves.

Parameters:

  • $participant: mixed
  • $muted: bool

setParticipantVolume(mixed $participant, int $volume): static

Set our local playback volume of a participant.

Parameters:

  • $participant: mixed
  • $volume: int From 1 to 20000, where 10000 is 100%.

setVideoPaused(bool $paused): static

Pause or resume our own video stream, telling the other participants to keep showing the last frame rather than hiding it.

Parameters:

  • $paused: bool

setJoinMuted(bool $joinMuted): static

Whether new participants join muted (admins only).

Parameters:

  • $joinMuted: bool

resetInviteHash(): static

Invalidate every invite link exported so far (admins only).

isStreamMode(): bool

Whether the server switched us to stream mode »: the call’s media is received by downloading chunks rather than over WebRTC, and there is a single
mixed stream to record (see {@see Call::setOutput()}) rather than one per participant.

isRtmpMode(): bool

Whether the call’s media is published by a single external RTMP publisher (an RTMP livestream).

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