EventTarget

Event handling of WebRTC objects.

The native WebRTC engine emits events on its own threads, which only schedule them. Handlers run on the asyncio event loop they were registered from.

webrtc.utils.events.Handler

A handler, which is a function or a coroutine function called with the webrtc.Event of an event

alias of Callable[[webrtc.Event], object]

webrtc.utils.events.AnyHandler

Any handler, which takes the event class of its event, like webrtc.RTCTrackEvent

alias of Callable[[Never], object]

class webrtc.utils.events.HandlerDecorator(*args, **kwargs)

The decorator returned by on() and once() without a handler, which registers the decorated one.

webrtc.utils.events.call_handler(loop, handler, event, *, message)

Calls a handler; exceptions, async ones too, go to the loop’s exception handler.

class webrtc.utils.events.EventTarget

The base class of objects that emit events.

Handlers are registered with on() or once() by event name, from a running asyncio event loop, and are called on that loop with one event object. They can be functions or coroutine functions, and a coroutine is run as a task. An exception in a handler goes to the exception handler of the loop, and doesn’t stop the other handlers. A handler registered twice for an event is called once.

See MDN: EventTarget.

Example:

@pc.on('icecandidate')
async def on_candidate(event):
    await signaling.send(event.candidate)


pc.on('track', lambda event: print(event.track))
off(name=None, handler=None)

Removes one handler or all of them, for one event or for all events.

See MDN: EventTarget/removeEventListener.

Parameters:

  • name (str, optional) – The name of the event. If omitted, every event.

  • handler (callable, optional) – The handler to remove. If omitted, every handler.

Raises:

ValueError – If the object has no such event.

remove_listener(name, handler)

Removes a handler of an event. Removing one that isn’t registered does nothing.

See MDN: EventTarget/removeEventListener.

Parameters:

  • name (str) – The name of the event.

  • handler (callable) – The handler to remove.

Raises:

ValueError – If the object has no such event.

remove_all_listeners(name=None)

Removes every handler of an event, or of all events.

Parameters:

name (str, optional) – The name of the event. If omitted, every event.

Raises:

ValueError – If the object has no such event.

listeners(name)

Returns the handlers of an event, in the order they were registered.

Parameters:

name (str) – The name of the event.

Returns:

list of callable – The handlers.

Raises:

ValueError – If the object has no such event.

Return type:

list[Callable[[Never], object]]

event_names()

Returns the names of the events that have handlers.

Returns:

set of str – The names.

Return type:

set[str]

class webrtc.utils.events.UniformEventTarget

An EventTarget whose events all have the same event class, which typed handlers take.

on(name: _N_contra, handler: None = None) → HandlerDecorator[_E]
on(name: _N_contra, handler: Callable[[_E], _R]) → Callable[[_E], _R]

Registers a handler of an event. Can be used as a decorator.

See MDN: EventTarget/addEventListener.

Parameters:

  • name (str) – The name of the event, like 'icecandidate'.

  • handler (callable, optional) – A function or a coroutine function called with the event object. If omitted, a decorator is returned.

Returns:

callable – The handler, or a decorator registering it.

Raises:
Return type:

object

once(name: _N_contra, handler: None = None) → HandlerDecorator[_E]
once(name: _N_contra, handler: Callable[[_E], _R]) → Callable[[_E], _R]

Registers a handler that is removed before its first call. Can be used as a decorator.

See MDN: EventTarget/addEventListener.

Parameters:

  • name (str) – The name of the event.

  • handler (callable, optional) – A function or a coroutine function called with the event object. If omitted, a decorator is returned.

Returns:

callable – The handler, or a decorator registering it.

Raises:
Return type:

object