@callback handle_answer(sdp :: String.t(), direction(), state()) ::
  {:ok, modified_sdp :: String.t(), state()}
  | {:reject, reason :: term(), state()}
  | {:noreply, state()}

Process an SDP answer.

Called before the media session finalizes an SDP answer.

Parameters

• sdp - The SDP answer as a string
• direction - :inbound or :outbound
• state - Current handler state

Returns

• {:ok, modified_sdp, state} - Use modified SDP
• {:reject, reason, state} - Reject the answer
• {:noreply, state} - Process SDP without modification

@callback handle_codec_negotiation(
  offered_codecs :: [codec()],
  supported_codecs :: [codec()],
  state()
) ::
  {:ok, codec(), state()}
  | {:ok, [codec()], state()}
  | {:error, :no_common_codec, state()}

Customize codec selection.

Called during SDP negotiation to select the best codec from offered and supported lists.

Parameters

• offered_codecs - Codecs offered by remote party
• supported_codecs - Codecs supported locally
• state - Current handler state

Returns

• {:ok, codec, state} - Select a single codec
• {:ok, codec_list, state} - Return ordered preference list
• {:error, :no_common_codec, state} - No acceptable codec

Example

@impl true
def handle_codec_negotiation(offered, supported, state) do
  # Prefer Opus > G.711μ > G.711A
  cond do
    :opus in offered and :opus in supported ->
      {:ok, :opus, state}
    :pcmu in offered and :pcmu in supported ->
      {:ok, :pcmu, state}
    :pcma in offered and :pcma in supported ->
      {:ok, :pcma, state}
    true ->
      {:error, :no_common_codec, state}
  end
end

@callback handle_media_request(request :: term(), state()) ::
  media_action()
  | {media_action(), state()}
  | {:error, reason :: term(), state()}

Handle custom media requests.

Allows for extensibility with custom requests.

Parameters

• request - Custom request
• state - Current handler state

Returns

• media_action - Action to execute
• {media_action, state} - Action with state update
• {:error, reason, state} - Invalid request

@callback handle_negotiation_complete(
  local_sdp :: String.t(),
  remote_sdp :: String.t(),
  selected_codec :: codec(),
  state()
) :: {:ok, state()} | {:error, reason :: term(), state()}

Called after SDP negotiation completes.

Provides the final negotiated parameters.

Parameters

• local_sdp - Final local SDP
• remote_sdp - Final remote SDP
• selected_codec - The negotiated codec
• state - Current handler state

Returns

• {:ok, state} - Negotiation accepted
• {:error, reason, state} - Reject the negotiation

@callback handle_offer(sdp :: String.t(), direction(), state()) ::
  {:ok, modified_sdp :: String.t(), state()}
  | {:reject, reason :: term(), state()}
  | {:noreply, state()}

Process an SDP offer.

Called before the media session processes an SDP offer. The handler can modify the SDP or reject it.

Parameters

• sdp - The SDP offer as a string
• direction - :inbound or :outbound
• state - Current handler state

Returns

• {:ok, modified_sdp, state} - Use modified SDP
• {:reject, reason, state} - Reject the offer
• {:noreply, state} - Process SDP without modification

@callback handle_play_complete(file_path :: String.t(), state()) ::
  media_action() | {media_action(), state()} | {:noreply, state()}

Handle playback completion.

Called when an audio file finishes playing.

Parameters

• file_path - Path of completed file
• state - Current handler state

Returns

• media_action - Next action to execute
• {media_action, state} - Action with state update
• {:noreply, state} - No action

@callback handle_session_start(session_id(), opts :: keyword(), state()) ::
  {:ok, state()} | {:error, reason :: term(), state()}

Handle media session start.

Called when a media session is being established.

Parameters

• session_id - Unique session identifier
• opts - Session options
• state - Current handler state

Returns

• {:ok, state} - Session started successfully
• {:error, reason, state} - Session start failed

@callback handle_session_stop(session_id(), reason :: term(), state()) :: {:ok, state()}

Handle media session stop.

Called when a media session is terminating.

Parameters

• session_id - Session identifier
• reason - Termination reason
• state - Current handler state

Returns

• {:ok, state} - Acknowledged

@callback handle_stream_error(session_id(), error :: term(), state()) ::
  {:retry, state()} | {:continue, state()} | {:stop, reason :: term(), state()}

Handle media stream errors.

Parameters

• session_id - Session identifier
• error - Error details
• state - Current handler state

Returns

• {:retry, state} - Retry the operation
• {:continue, state} - Continue despite error
• {:stop, reason, state} - Stop the stream

@callback handle_stream_start(
  session_id(),
  direction :: :inbound | :outbound | :bidirectional,
  state()
) ::
  media_action()
  | {media_action(), state()}
  | {[media_action()], state()}
  | {:noreply, state()}

Handle media stream start.

Called when media stream is about to start. Can return media actions to execute.

Parameters

• session_id - Session identifier
• direction - :inbound, :outbound, or :bidirectional
• state - Current handler state

Returns

• media_action - Single action to execute
• {media_action, state} - Action with state update
• {[media_action], state} - Multiple actions
• {:noreply, state} - No action

Example

@impl true
def handle_stream_start(_session_id, :inbound, state) do
  # Play welcome message
  {{:play, "/audio/welcome.wav"}, state}
end

@callback handle_stream_stop(session_id(), reason :: term(), state()) :: {:ok, state()}

Handle media stream stop.

Called when media stream stops.

Parameters

• session_id - Session identifier
• reason - Stop reason
• state - Current handler state

Returns

• {:ok, state} - Acknowledged

@callback init(args :: term()) :: {:ok, state()} | {:stop, reason :: term()}

Initialize the media handler.

Called when a new media session starts. This happens when MediaSession is started for a dialog.

Parameters

• args - Arguments passed when starting the handler

Returns

• {:ok, state} - Initialize with the given state
• {:stop, reason} - Prevent the handler from starting

Example

@impl true
def init(args) do
  {:ok, %{
    preferred_codec: :opus,
    quality_threshold: 5.0,
    play_queue: []
  }}
end