whatsapp-chatbot-python 1.0.0__tar.gz → 1.1.0__tar.gz

{whatsapp_chatbot_python-1.0.0 → whatsapp_chatbot_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whatsapp-chatbot-python
-Version: 1.0.0
+Version: 1.1.0
 Summary: This library helps you easily create a Python chatbot with WhatsApp API.
 Home-page: https://github.com/green-api/whatsapp-chatbot-python
 Author: GREEN API
@@ -593,20 +593,25 @@ credentials:
 ```python
 import asyncio
 import logging
-import os
 
 from whatsapp_chatbot_python.calls import (
     CallEvent, CallSession, CallStateMachine,
 )
 from whatsapp_chatbot_python.calls.service import WhatsAppCallService
 
+id_instance = "ID_INSTANCE"
+api_token_instance = "API_TOKEN"
+openai_api_key = "OPENAI_KEY"
+realtime_model = "gpt-realtime-2.1"
+realtime_voice = "marin"
+
 service = WhatsAppCallService(
     api_url="https://api.green-api.com",
-    id_instance=os.environ["ID_INSTANCE"],
-    api_token_instance=os.environ["API_TOKEN_INSTANCE"],
-    openai_api_key=os.environ["OPENAI_API_KEY"],
-    realtime_model=os.environ["REALTIME_MODEL"],
-    realtime_voice=os.environ["REALTIME_VOICE"],
+    id_instance=id_instance,
+    api_token_instance=api_token_instance,
+    openai_api_key=openai_api_key,
+    realtime_model=realtime_model,
+    realtime_voice=realtime_voice,
     ring_timeout_seconds=30,
     talk_timeout_seconds=120,
     shutdown_timeout_seconds=10,
@@ -623,18 +628,55 @@ async def call_once():
     fsm.apply(session, CallEvent.ENQUEUED)
     fsm.apply(session, CallEvent.DEQUEUED)
     result = await service.execute(session, fsm.apply)
-    try:
+    with result:
         print(session.state, session.end_reason, session.error_code)
         if result.recording_path is not None:
             print("MP3:", result.recording_path)
-            # Upload or copy the recording here, before removing it.
-    finally:
-        if result.recording_path is not None:
-            result.recording_path.unlink(missing_ok=True)
+            # Upload or copy it here; the context removes the temporary file.
 
 asyncio.run(call_once())
 ```
 
+`with result:` removes an unclaimed MP3 after use. Call `result.take_recording()`
+to keep the file. `CallOptions(input_audio=InputAudioOptions(...))` configures the
+bounded queue from RTC audio to the voice model; a full queue fails the call.
+Cleanup timeouts mean resource closure is unconfirmed, not complete. The service
+then reports `healthy=False` and rejects subsequent calls. The installed RTC SDK
+can leave signaling open if its own close operation never finishes; restart the
+worker after investigating such a failure.
+
+### Accept an incoming call
+
+The application owns its queue, offer deduplication and notification parsing. An incoming offer can share the same queue
+and worker as outgoing calls. Create its deadline when the offer arrives, using the time remaining from the offer
+timestamp. For example, a 60-second application limit becomes `monotonic() + remaining_seconds`; the library has no
+fixed incoming ring limit. The deadline includes time spent in the queue and in call setup. Coordinators can type their
+executor as `IncomingCallExecutor`, which extends the existing `CallExecutor` with the two incoming call-control
+methods.
+
+```python
+from time import monotonic
+from whatsapp_chatbot_python.calls import CallEvent, CallSession, CallStateMachine
+
+session = CallSession.incoming(
+    sender_id=caller_id,
+    call_id=call_id,
+    language="en",
+    incoming_deadline=monotonic() + remaining_seconds,
+    greeting_text="Hello! This is a WhatsApp demo call. What would you like to discuss?",
+)
+fsm = CallStateMachine()
+fsm.apply(session, CallEvent.ENQUEUED)
+app_queue.put(session)
+
+if monotonic() >= session.incoming_deadline:
+    fsm.apply(session, CallEvent.INCOMING_EXPIRED)
+    await service.reject_incoming(session.call_id, session.sender_id)
+else:
+    fsm.apply(session, CallEvent.DEQUEUED)
+    result = await service.execute(session, transition_under_app_lock)
+```
+
 ## Service methods documentation
 
 [Service methods documentation](https://green-api.com/en/docs/api/)

{whatsapp_chatbot_python-1.0.0 → whatsapp_chatbot_python-1.1.0}/README.md

@@ -541,20 +541,25 @@ credentials:
 ```python
 import asyncio
 import logging
-import os
 
 from whatsapp_chatbot_python.calls import (
     CallEvent, CallSession, CallStateMachine,
 )
 from whatsapp_chatbot_python.calls.service import WhatsAppCallService
 
+id_instance = "ID_INSTANCE"
+api_token_instance = "API_TOKEN"
+openai_api_key = "OPENAI_KEY"
+realtime_model = "gpt-realtime-2.1"
+realtime_voice = "marin"
+
 service = WhatsAppCallService(
     api_url="https://api.green-api.com",
-    id_instance=os.environ["ID_INSTANCE"],
-    api_token_instance=os.environ["API_TOKEN_INSTANCE"],
-    openai_api_key=os.environ["OPENAI_API_KEY"],
-    realtime_model=os.environ["REALTIME_MODEL"],
-    realtime_voice=os.environ["REALTIME_VOICE"],
+    id_instance=id_instance,
+    api_token_instance=api_token_instance,
+    openai_api_key=openai_api_key,
+    realtime_model=realtime_model,
+    realtime_voice=realtime_voice,
     ring_timeout_seconds=30,
     talk_timeout_seconds=120,
     shutdown_timeout_seconds=10,
@@ -571,18 +576,55 @@ async def call_once():
     fsm.apply(session, CallEvent.ENQUEUED)
     fsm.apply(session, CallEvent.DEQUEUED)
     result = await service.execute(session, fsm.apply)
-    try:
+    with result:
         print(session.state, session.end_reason, session.error_code)
         if result.recording_path is not None:
             print("MP3:", result.recording_path)
-            # Upload or copy the recording here, before removing it.
-    finally:
-        if result.recording_path is not None:
-            result.recording_path.unlink(missing_ok=True)
+            # Upload or copy it here; the context removes the temporary file.
 
 asyncio.run(call_once())
 ```
 
+`with result:` removes an unclaimed MP3 after use. Call `result.take_recording()`
+to keep the file. `CallOptions(input_audio=InputAudioOptions(...))` configures the
+bounded queue from RTC audio to the voice model; a full queue fails the call.
+Cleanup timeouts mean resource closure is unconfirmed, not complete. The service
+then reports `healthy=False` and rejects subsequent calls. The installed RTC SDK
+can leave signaling open if its own close operation never finishes; restart the
+worker after investigating such a failure.
+
+### Accept an incoming call
+
+The application owns its queue, offer deduplication and notification parsing. An incoming offer can share the same queue
+and worker as outgoing calls. Create its deadline when the offer arrives, using the time remaining from the offer
+timestamp. For example, a 60-second application limit becomes `monotonic() + remaining_seconds`; the library has no
+fixed incoming ring limit. The deadline includes time spent in the queue and in call setup. Coordinators can type their
+executor as `IncomingCallExecutor`, which extends the existing `CallExecutor` with the two incoming call-control
+methods.
+
+```python
+from time import monotonic
+from whatsapp_chatbot_python.calls import CallEvent, CallSession, CallStateMachine
+
+session = CallSession.incoming(
+    sender_id=caller_id,
+    call_id=call_id,
+    language="en",
+    incoming_deadline=monotonic() + remaining_seconds,
+    greeting_text="Hello! This is a WhatsApp demo call. What would you like to discuss?",
+)
+fsm = CallStateMachine()
+fsm.apply(session, CallEvent.ENQUEUED)
+app_queue.put(session)
+
+if monotonic() >= session.incoming_deadline:
+    fsm.apply(session, CallEvent.INCOMING_EXPIRED)
+    await service.reject_incoming(session.call_id, session.sender_id)
+else:
+    fsm.apply(session, CallEvent.DEQUEUED)
+    result = await service.execute(session, transition_under_app_lock)
+```
+
 ## Service methods documentation
 
 [Service methods documentation](https://green-api.com/en/docs/api/)

{whatsapp_chatbot_python-1.0.0 → whatsapp_chatbot_python-1.1.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", encoding="UTF-8") as file:
 
 setup(
     name="whatsapp-chatbot-python",
-    version="1.0.0",
+    version="1.1.0",
     description=(
         "This library helps you easily create"
         " a Python chatbot with WhatsApp API."

{whatsapp_chatbot_python-1.0.0 → whatsapp_chatbot_python-1.1.0}/tests/test_calls_imports.py

@@ -23,18 +23,20 @@ class BlockOptionalImports(importlib.abc.MetaPathFinder):
             raise ImportError("optional dependency blocked: " + fullname)
 
 sys.meta_path.insert(0, BlockOptionalImports())
-from whatsapp_chatbot_python import GreenAPIBot, Notification
+from whatsapp_chatbot_python import GreenAPIBot, IncomingCall, IncomingCallNotification, Notification
+assert IncomingCallNotification.__name__ == "IncomingCallNotification"
 assert "whatsapp_chatbot_python.calls" not in sys.modules
 ''')
 
     @unittest.skipIf(sys.version_info < (3, 11), "call contracts require Python 3.11+")
-    def test_contracts_do_not_load_call_implementation(self):
+    def test_public_call_import_does_not_load_optional_media_dependencies(self):
         self.run_script('''
 import sys
-from whatsapp_chatbot_python.calls import CallSession, CallStateMachine
+from whatsapp_chatbot_python.calls import CallDirection, CallSession, CallStateMachine, IncomingCallExecutor
 assert CallSession("sender", "chat", "en").state == "triggered"
-assert "whatsapp_chatbot_python.calls.service" not in sys.modules
-assert "whatsapp_chatbot_python.calls.realtime_voice" not in sys.modules
+assert CallSession("sender", "chat", "en").direction == CallDirection.OUTGOING
+assert IncomingCallExecutor.__name__ == "IncomingCallExecutor"
+assert "whatsapp_chatbot_python.calls.service" in sys.modules
 assert "openai" not in sys.modules
 assert "aiortc" not in sys.modules
 assert "av" not in sys.modules

whatsapp_chatbot_python-1.1.0/tests/test_incoming_call_notifications.py

@@ -0,0 +1,112 @@
+import logging
+import unittest
+from unittest.mock import Mock
+
+from whatsapp_chatbot_python import IncomingCall, IncomingCallNotification, Notification
+from whatsapp_chatbot_python.manager.router import Router
+
+
+class IncomingCallNotificationTest(unittest.TestCase):
+    def setUp(self):
+        self.api = Mock()
+        self.router = Router(self.api, logging.getLogger(__name__))
+
+    @staticmethod
+    def event(status="offer", timestamp=1_700_000_000):
+        return {
+            "typeWebhook": "incomingCall", "from": "caller@c.us",
+            "idMessage": "call-1", "status": status, "timestamp": timestamp,
+        }
+
+    def test_typed_notification_keeps_original_webhook_and_message_methods_work(self):
+        received = []
+        self.router.incoming_call.add_handler(received.append)
+        event = self.event(status="future-status")
+
+        self.router.route_event(event)
+
+        notification = received[0]
+        self.assertIsInstance(notification, IncomingCallNotification)
+        self.assertIsInstance(notification, Notification)
+        self.assertIs(notification.event, event)
+        self.assertIs(notification.raw_event, event)
+        self.assertIs(notification.call.raw_event, event)
+        self.assertEqual(notification.call, IncomingCall("caller@c.us", "call-1", "future-status", 1_700_000_000.0))
+        self.assertEqual(notification.call.chat_id, "caller@c.us")
+        self.assertEqual((notification.sender, notification.chat, notification.get_id_message()),
+                         ("caller@c.us", "caller@c.us", "call-1"))
+        self.assertIsNone(notification.message_text)
+        self.assertIsNone(notification.get_message_data())
+
+        notification.answer("Hello")
+        self.api.sending.sendMessage.assert_called_once_with(
+            "caller@c.us", "Hello", None, None, None, None,
+        )
+
+    def test_call_and_message_observers_share_state_only_with_each_other(self):
+        state_manager = self.router.message.state_manager
+        self.assertIs(self.router.incoming_call.state_manager, state_manager)
+        self.assertIsNot(self.router.outgoing_message.state_manager, state_manager)
+        state_manager.set_state("caller@c.us", "MENU")
+        state_manager.set_state_data("caller@c.us", {"language_code": "ru"})
+        received = []
+
+        @self.router.incoming_call(status="offer", state="MENU", from_sender="caller@c.us")
+        def on_offer(notification):
+            received.append(notification.state_manager.get_state_data(notification.call.sender))
+
+        self.router.route_event(self.event())
+        self.assertEqual(received, [{"language_code": "ru"}])
+
+        state_manager.update_state("caller@c.us", "DONE")
+        self.router.route_event(self.event())
+        self.assertEqual(len(received), 1)
+
+    def test_status_filter_accepts_one_or_many_values_and_unknown_status_is_routed(self):
+        offers, ended, other = [], [], []
+        self.router.incoming_call.add_handler(offers.append, status="offer")
+        self.router.incoming_call.add_handler(ended.append, status=["declined", "hungUp"])
+        self.router.incoming_call.add_handler(other.append)
+
+        for status in ("offer", "declined", "hungUp", "new-status"):
+            self.router.route_event(self.event(status=status))
+
+        self.assertEqual([item.call.status for item in offers], ["offer"])
+        self.assertEqual([item.call.status for item in ended], ["declined", "hungUp"])
+        self.assertEqual([item.call.status for item in other], ["new-status"])
+
+    def test_invalid_call_filters_fail_at_registration(self):
+        for filters in ({"status": None}, {"status": []}, {"status": 123},
+                        {"status": ["offer", ""]}, {"command": "start"}):
+            with self.subTest(filters=filters), self.assertRaises(ValueError):
+                self.router.incoming_call.add_handler(lambda notification: None, **filters)
+        self.assertEqual(self.router.incoming_call.handlers, [])
+
+    def test_timestamps_and_missing_fields_are_safe(self):
+        for value, expected in ((1_700_000_000, 1_700_000_000.0),
+                                (1_700_000_000_000, 1_700_000_000.0),
+                                (1_700_000_000_000_000, 1_700_000_000.0),
+                                (946_684_800, 946_684_800.0),
+                                (4_102_444_800, None),
+                                (1_700_000_000_000_000_000, None),
+                                (12_345_678_901_234_567_890, None),
+                                (True, None), (float("nan"), None), (10 ** 1000, None)):
+            with self.subTest(timestamp=value):
+                self.assertEqual(IncomingCall.from_event(self.event(timestamp=value)).timestamp, expected)
+        self.assertEqual(IncomingCall.from_event({}), IncomingCall(None, None, None, None))
+
+    def test_existing_message_notification_remains_unchanged(self):
+        received = []
+        self.router.message.add_handler(received.append)
+        event = {
+            "typeWebhook": "incomingMessageReceived",
+            "senderData": {"sender": "caller@c.us", "chatId": "caller@c.us"},
+            "messageData": {"typeMessage": "textMessage", "textMessageData": {"textMessage": "Hi"}},
+        }
+        self.router.route_event(event)
+        self.assertIs(type(received[0]), Notification)
+        self.assertEqual(received[0].message_text, "Hi")
+
+
+if __name__ == "__main__":
+    unittest.main()

{whatsapp_chatbot_python-1.0.0 → whatsapp_chatbot_python-1.1.0}/whatsapp_chatbot_python/__init__.py

@@ -1,5 +1,6 @@
 from .bot import Bot, GreenAPI, GreenAPIBot, GreenAPIError, GreenAPIBotError
 from .manager.handler import Notification
+from .manager.incoming_call import IncomingCall, IncomingCallNotification
 from .manager.state import BaseStates
 
 __all__ = [
@@ -9,5 +10,7 @@ __all__ = [
     "GreenAPIError",
     "GreenAPIBotError",
     "Notification",
+    "IncomingCall",
+    "IncomingCallNotification",
     "BaseStates"
 ]

whatsapp_chatbot_python-1.1.0/whatsapp_chatbot_python/calls/__init__.py

@@ -0,0 +1,37 @@
+"""Call contracts import without installing the optional VoIP dependencies."""
+import sys
+
+if sys.version_info < (3, 11):
+    raise ImportError("whatsapp_chatbot_python.calls requires Python 3.11 or newer")
+
+from .models import (
+    CallDirection,
+    CallEndReason,
+    CallEvent,
+    CallExecutionResult,
+    CallExecutor,
+    CallOptions,
+    CallSession,
+    CallServiceUnavailable,
+    CallState,
+    IncomingCallExecutor,
+    InputAudioOptions,
+    PlaybackOptions,
+    ProviderError,
+    RecordingOptions,
+    StateTransition,
+    TransitionCallback,
+    ACTIVE_STATES,
+    TERMINAL_STATES,
+    WAITING_STATES,
+)
+
+from .service import WhatsAppCallService
+from .state_machine import CallStateMachine
+
+__all__ = [
+    "ACTIVE_STATES", "TERMINAL_STATES", "WAITING_STATES", "CallDirection", "CallEndReason", "CallEvent",
+    "CallExecutionResult", "CallExecutor", "CallOptions", "CallSession", "CallServiceUnavailable", "CallState",
+    "CallStateMachine", "IncomingCallExecutor", "InputAudioOptions", "PlaybackOptions", "ProviderError",
+    "RecordingOptions", "StateTransition", "TransitionCallback", "WhatsAppCallService",
+]

whatsapp_chatbot_python-1.1.0/whatsapp_chatbot_python/calls/audio.py

@@ -0,0 +1,279 @@
+"""PCM/RTC boundary. Audio tracks depend on narrow source/sink interfaces."""
+from __future__ import annotations
+
+import asyncio
+from fractions import Fraction
+from math import ceil, isfinite
+from time import monotonic
+from typing import Protocol
+
+from aiortc import AudioStreamTrack
+from aiortc.mediastreams import MediaStreamError
+from av import AudioFrame, AudioResampler
+from whatsapp_api_client_python.tools.voip.audio import CallAudio
+
+from .models import EventSink, InputAudioOptions, MediaFailed, PcmChunk, PCM, PCM16_SAMPLE_BYTES
+from .recorder import CallRecorder, Track
+
+
+class AudioSource(Protocol):
+    def read_frame(self) -> bytes: ...
+    def replace_track(self) -> None: ...
+
+
+class AudioSink(Protocol):
+    async def write_audio(self, data: bytes) -> None: ...
+
+
+class RecordingTap:
+    """Align each track once, then advance by sample count, not arrival jitter."""
+    def __init__(self, recorder: CallRecorder) -> None:
+        self._recorder = recorder
+        self._epoch: float | None = None
+        self._positions: dict[Track, int] = {}
+        self._media_origins: dict[Track, tuple[float, int]] = {}
+
+    def activate(self) -> None:
+        if self._epoch is None:
+            self._epoch = monotonic()
+
+    def write(self, track: Track, data: bytes, media_time: float | None = None) -> None:
+        if self._epoch is None:
+            return
+
+        position = self._positions.setdefault(
+            track,
+            max(0, int((monotonic() - self._epoch) * PCM.rate))
+        )
+
+        if media_time is not None and isfinite(media_time):
+            origin_time, origin_position = self._media_origins.setdefault(
+                track,
+                (media_time, position),
+            )
+
+            position = max(position, origin_position + round((media_time - origin_time) * PCM.rate))
+
+        try:
+            self._recorder.write(track, PcmChunk(position, data))
+        except Exception as error:
+            self._recorder.disable(error)
+            return
+
+        self._positions[track] = position + len(data) // PCM16_SAMPLE_BYTES
+
+    def replace_tracks(self) -> None:
+        self._positions.clear()
+        self._media_origins.clear()
+
+
+class BotTrack(AudioStreamTrack):
+    def __init__(self, source: AudioSource, tap: RecordingTap, emit: EventSink) -> None:
+        super().__init__()
+        self._source = source
+        self._tap = tap
+        self._emit = emit
+        self._position = 0
+        self._epoch = monotonic()
+
+    async def recv(self) -> AudioFrame:
+        if self.readyState != "live":
+            raise MediaStreamError
+
+        try:
+            return await self._next_frame()
+        except Exception as error:
+            self._emit(MediaFailed(error))
+            raise
+
+    async def _next_frame(self) -> AudioFrame:
+        due = self._epoch + self._position / PCM.rate
+
+        await asyncio.sleep(max(0, due - monotonic()))
+
+        data = self._source.read_frame()
+
+        if len(data) != PCM.bytes_per_frame:
+            raise ValueError("AudioSource must return exactly one PCM frame")
+
+        self._tap.write(Track.BOT, data)
+
+        frame = AudioFrame(
+            format=PCM.av_format,
+            layout=PCM.layout,
+            samples=PCM.samples_per_frame,
+        )
+
+        frame.planes[0].update(data)
+
+        frame.sample_rate = PCM.rate
+        frame.pts = self._position
+        frame.time_base = Fraction(1, PCM.rate)
+        self._position += PCM.samples_per_frame
+
+        return frame
+
+
+class CallerSink:
+    def __init__(
+        self, sink: AudioSink, tap: RecordingTap, emit: EventSink,
+        options: InputAudioOptions | None = None,
+    ) -> None:
+        self._sink = sink
+        self._tap = tap
+        self._emit = emit
+        self._options = options or InputAudioOptions()
+        self._tasks: set[asyncio.Task] = set()
+        self._closing = False
+        self._failure_reported = False
+
+    async def attach(self, track) -> None:
+        if self._closing:
+            raise RuntimeError("Caller audio sink is closing")
+
+        task = asyncio.create_task(self._consume(track))
+        self._tasks.add(task)
+        task.add_done_callback(self._done)
+
+    async def _consume(self, track) -> None:
+        resampler = AudioResampler(format=PCM.av_format, layout=PCM.layout, rate=PCM.rate)
+        capacity = max(1, ceil(self._options.buffer_seconds / PCM.frame_seconds))
+        queue: asyncio.Queue[bytes] = asyncio.Queue(maxsize=capacity)
+        finished = asyncio.Event()
+        sender = asyncio.create_task(self._send(queue, finished), name="call:input-send")
+        reader = asyncio.current_task()
+        sender.add_done_callback(lambda done: self._sender_done(done, reader))
+        stream_ended = False
+
+        try:
+            while True:
+                for frame in resampler.resample(await track.recv()):
+                    if sender.done():
+                        return
+
+                    size = frame.samples * PCM16_SAMPLE_BYTES
+                    data = bytes(frame.planes[0])[:size]
+
+                    media_time = (
+                        float(frame.pts * frame.time_base)
+                        if frame.pts is not None and frame.time_base is not None else None
+                    )
+
+                    self._tap.write(Track.CALLER, data, media_time)
+                    self._enqueue(queue, data)
+        except MediaStreamError:
+            stream_ended = True
+        finally:
+            finished.set()
+
+            if not stream_ended:
+                sender.cancel()
+            await asyncio.gather(sender, return_exceptions=True)
+
+    def _sender_done(self, sender: asyncio.Task, reader: asyncio.Task) -> None:
+        if sender.cancelled() or self._closing:
+            return
+
+        error = sender.exception()
+
+        if error is not None:
+            self._report_failure(error)
+
+            if not reader.done():
+                reader.cancel()
+
+    def _report_failure(self, error: Exception) -> None:
+        if not self._failure_reported:
+            self._failure_reported = True
+            self._emit(MediaFailed(error))
+
+    @staticmethod
+    def _enqueue(queue: asyncio.Queue[bytes], data: bytes) -> None:
+        for start in range(0, len(data), PCM.bytes_per_frame):
+            try:
+                queue.put_nowait(data[start:start + PCM.bytes_per_frame])
+            except asyncio.QueueFull as error:
+                raise BufferError("Inbound audio buffer exceeded its time limit") from error
+
+    async def _send(self, queue: asyncio.Queue[bytes], finished: asyncio.Event) -> None:
+        while not finished.is_set() or not queue.empty():
+            try:
+                data = await asyncio.wait_for(queue.get(), PCM.frame_seconds)
+            except TimeoutError:
+                continue
+
+            await asyncio.wait_for(self._sink.write_audio(data), self._options.send_seconds)
+
+    def _done(self, task: asyncio.Task) -> None:
+        self._tasks.discard(task)
+
+        if task.cancelled():
+            return
+
+        error = task.exception()
+
+        if error is not None:
+            self._report_failure(error)
+
+    async def close(self) -> None:
+        self._closing = True
+        tasks = tuple(self._tasks)
+
+        for task in tasks:
+            task.cancel()
+
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+class AudioBridge:
+    def __init__(
+        self,
+        source: AudioSource,
+        sink: AudioSink,
+        recorder: CallRecorder,
+        emit: EventSink,
+        input_options: InputAudioOptions | None = None,
+    ) -> None:
+        self._source = source
+        self._sink = sink
+        self._tap = RecordingTap(recorder)
+        self._emit = emit
+        self._input_options = input_options
+        self._audio: CallAudio | None = None
+        self._closed = False
+
+    def activate_recording(self) -> None:
+        self._tap.activate()
+
+    async def create(self) -> CallAudio:
+        if self._closed:
+            raise RuntimeError("Audio bridge is closing")
+
+        await self._close_current()
+
+        if self._closed:
+            raise RuntimeError("Audio bridge is closing")
+
+        self._source.replace_track()
+        self._tap.replace_tracks()
+
+        local = BotTrack(self._source, self._tap, self._emit)
+        remote = CallerSink(self._sink, self._tap, self._emit, self._input_options)
+
+        async def close_pair() -> None:
+            local.stop()
+            await remote.close()
+
+        self._audio = CallAudio(local, remote.attach, close_pair)
+
+        return self._audio
+
+    async def close(self) -> None:
+        self._closed = True
+        await self._close_current()
+
+    async def _close_current(self) -> None:
+        audio, self._audio = self._audio, None
+
+        if audio is not None:
+            await audio.close()