Group PJMED_STRM

group PJMED_STRM

Communicating with remote peer via the network.

A media stream is a bidirectional multimedia communication between two endpoints. It corresponds to a media description (m= line) in SDP session descriptor.

A media stream consists of two unidirectional channels:

  • encoding channel, which transmits unidirectional media to remote, and

  • decoding channel, which receives unidirectional media from remote.

A media stream exports media port interface (see Media Ports Framework) and application normally uses this interface to interconnect the stream to other PJMEDIA components.

A media stream internally manages the following objects:

Streams are created by calling pjmedia_stream_create(), specifying pjmedia_stream_info structure in the parameter. Application can construct the pjmedia_stream_info structure manually, or use pjmedia_stream_info_from_sdp() or pjmedia_session_info_from_sdp() functions to construct the pjmedia_stream_info from local and remote SDP session descriptors.

Application can also use Media Sessions to indirectly create the streams.

Typedefs

typedef struct pjmedia_channel pjmedia_channel

Opaque declaration for media channel. Media channel is unidirectional flow of media from sender to receiver.

Enums

enum pjmedia_stream_dtmf_event_flags

This enumeration defines flags used by pjmedia_stream_dtmf_event.

Values:

enumerator PJMEDIA_STREAM_DTMF_IS_UPDATE

The event was already indicated earlier. The new indication contains an updated event duration.

enumerator PJMEDIA_STREAM_DTMF_IS_END

The event has ended and the indication contains the final event duration. Note that end indications might get lost. Hence it is not guaranteed to receive an event with PJMEDIA_STREAM_DTMF_IS_END for every event.

Functions

pj_status_t pjmedia_stream_info_from_sdp(pjmedia_stream_info *si, pj_pool_t *pool, pjmedia_endpt *endpt, const pjmedia_sdp_session *local, const pjmedia_sdp_session *remote, unsigned stream_idx)

This function will initialize the stream info based on information in both SDP session descriptors for the specified stream index. The remaining information will be taken from default codec parameters. If socket info array is specified, the socket will be copied to the session info as well.

Parameters:

  • si – Stream info structure to be initialized.

  • pool – Pool to allocate memory.

  • endpt – PJMEDIA endpoint instance.

  • local – Local SDP session descriptor.

  • remote – Remote SDP session descriptor.

  • stream_idx – Media stream index in the session descriptor.

Returns:

PJ_SUCCESS if stream info is successfully initialized.

pj_status_t pjmedia_stream_create(pjmedia_endpt *endpt, pj_pool_t *pool, const pjmedia_stream_info *info, pjmedia_transport *tp, void *user_data, pjmedia_stream **p_stream)

Create a media stream based on the specified parameter. After the stream has been created, application normally would want to get the media port interface of the streams, by calling pjmedia_stream_get_port(). The media port interface exports put_frame() and get_frame() function, used to transmit and receive media frames from the stream.

Without application calling put_frame() and get_frame(), there will be no media frames transmitted or received by the stream.

Parameters:

  • endpt – Media endpoint.

  • pool – Pool to allocate memory for the stream. A large number of memory may be needed because jitter buffer needs to preallocate some storage.

  • info – Stream information.

  • tp – Stream transport instance used to transmit and receive RTP/RTCP packets to/from the underlying transport.

  • user_data – Arbitrary user data (for future callback feature).

  • p_stream – Pointer to receive the media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_destroy(pjmedia_stream *stream)

Destroy the media stream.

Parameters:

stream – The media stream.

Returns:

PJ_SUCCESS on success.

char pjmedia_stream_get_last_jb_frame_type(pjmedia_stream *stream)

Get the last frame type retreived from the jitter buffer.

Parameters:

stream – The media stream.

Returns:

Jitter buffer frame type.

pj_status_t pjmedia_stream_get_port(pjmedia_stream *stream, pjmedia_port **p_port)

Get the media port interface of the stream. The media port interface declares put_frame() and get_frame() function, which is the only way for application to transmit and receive media frames from the stream.

Parameters:

  • stream – The media stream.

  • p_port – Pointer to receive the port interface.

Returns:

PJ_SUCCESS on success.

pjmedia_transport *pjmedia_stream_get_transport(pjmedia_stream *st)

Get the media transport object associated with this stream.

Parameters:

st – The media stream.

Returns:

The transport object being used by the stream.

pj_status_t pjmedia_stream_start(pjmedia_stream *stream)

Start the media stream. This will start the appropriate channels in the media stream, depending on the media direction that was set when the stream was created.

Parameters:

stream – The media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_modify_codec_param(pjmedia_stream *stream, const pjmedia_codec_param *param)

Modify the stream’s codec parameter after the codec is opened. Note that not all codec parameters can be modified during run-time. Currently, only Opus codec supports changing key codec parameters such as bitrate and bandwidth, while other codecs may only be able to modify minor settings such as VAD or PLC.

Parameters:

  • stream – The media stream.

  • param – The new codec parameter.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_get_info(const pjmedia_stream *stream, pjmedia_stream_info *info)

Get the stream info.

Parameters:

  • stream – The media stream.

  • info – Stream info.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_get_stat(const pjmedia_stream *stream, pjmedia_rtcp_stat *stat)

Get the stream statistics. See also pjmedia_stream_get_stat_jbuf()

Parameters:

  • stream – The media stream.

  • stat – Media stream statistics.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_reset_stat(pjmedia_stream *stream)

Reset the stream statistics.

Parameters:

stream – The media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_get_stat_jbuf(const pjmedia_stream *stream, pjmedia_jb_state *state)

Get current jitter buffer state. See also pjmedia_stream_get_stat()

Parameters:

  • stream – The media stream.

  • state – Jitter buffer state.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_pause(pjmedia_stream *stream, pjmedia_dir dir)

Pause the individual channel in the stream.

Parameters:

  • stream – The media channel.

  • dir – Which direction to pause.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_resume(pjmedia_stream *stream, pjmedia_dir dir)

Resume the individual channel in the stream.

Parameters:

  • stream – The media channel.

  • dir – Which direction to resume.

Returns:

PJ_SUCCESS on success;

pj_status_t pjmedia_stream_dial_dtmf(pjmedia_stream *stream, const pj_str_t *ascii_digit)

Transmit DTMF to this stream. The DTMF will be transmitted uisng RTP telephone-events as described in RFC 2833. This operation is only valid for audio stream.

Parameters:

  • stream – The media stream.

  • ascii_digit – String containing digits to be sent to remote as described on RFC 2833 section 3.10. If PJMEDIA_HAS_DTMF_FLASH is enabled, character ‘R’ is used to represent the event type 16 (flash) as stated in RFC 4730. Currently the maximum number of digits are 32.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_dial_dtmf2(pjmedia_stream *stream, const pj_str_t *ascii_digit, unsigned duration)

Transmit DTMF to this stream. The DTMF will be transmitted using RTP telephone-events as described in RFC 2833. This operation is only valid for audio stream.

Parameters:

  • stream – The media stream.

  • ascii_digit – String containing digits to be sent to remote as described on RFC 2833 section 3.10. If PJMEDIA_HAS_DTMF_FLASH is enabled, character ‘R’ is used to represent the event type 16 (flash) as stated in RFC 4730. Currently the maximum number of digits are 32.

  • duration – duration of event in ms or 0 to use default

Returns:

PJ_SUCCESS on success.

pj_bool_t pjmedia_stream_check_dtmf(pjmedia_stream *stream)

Check if the stream has incoming DTMF digits in the incoming DTMF queue. Incoming DTMF digits received via RFC 2833 mechanism are saved in the incoming digits queue.

Parameters:

stream – The media stream.

Returns:

Non-zero (PJ_TRUE) if the stream has received DTMF digits in the .

pj_status_t pjmedia_stream_get_dtmf(pjmedia_stream *stream, char *ascii_digits, unsigned *size)

Retrieve the incoming DTMF digits from the stream, and remove the digits from stream’s DTMF buffer. Note that the digits buffer will not be NULL terminated.

Parameters:

  • stream – The media stream.

  • ascii_digits – Buffer to receive the digits. The length of this buffer is indicated in the “size” argument.

  • size – On input, contains the maximum digits to be copied to the buffer. On output, it contains the actual digits that has been copied to the buffer.

Returns:

Non-zero (PJ_TRUE) if the stream has received DTMF digits in the .

pj_status_t pjmedia_stream_set_dtmf_callback(pjmedia_stream *stream, void (*cb)(pjmedia_stream*, void *user_data, int digit), void *user_data)

Set callback to be called upon receiving DTMF digits. If callback is registered, the stream will not buffer incoming DTMF but rather call the callback as soon as DTMF digit is received completely. This callback will not be called if another callback is set via pjmedia_stream_set_dtmf_event_callback() as well.

Parameters:

  • stream – The media stream.

  • cb – Callback to be called upon receiving DTMF digits. The DTMF digits will be given to the callback as ASCII digits.

  • user_data – User data to be returned back when the callback is called.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_set_dtmf_event_callback(pjmedia_stream *stream, void (*cb)(pjmedia_stream*, void *user_data, const pjmedia_stream_dtmf_event *event), void *user_data)

Set callback to be called upon receiving DTMF digits. If callback is registered, the stream will not buffer incoming DTMF but rather call the callback as soon as DTMF digit is received.

Parameters:

  • stream – The media stream.

  • cb – Callback to be called upon receiving DTMF digits. See pjmedia_stream_dtmf_event.

  • user_data – User data to be returned back when the callback is called.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_send_rtcp_sdes(pjmedia_stream *stream)

Send RTCP SDES for the media stream.

Parameters:

stream – The media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_send_rtcp_bye(pjmedia_stream *stream)

Send RTCP BYE for the media stream.

Parameters:

stream – The media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_get_rtp_session_info(pjmedia_stream *stream, pjmedia_stream_rtp_sess_info *session_info)

Get the RTP session information of the media stream. This function can be useful for app with custom media transport to inject/filter some outgoing/incoming proprietary packets into normal audio RTP traffics. This will return the original pointer to the internal states of the stream, and generally it is not advisable for app to modify them.

Parameters:

  • stream – The media stream.

  • session_info – The stream session info.

Returns:

PJ_SUCCESS on success.

struct pjmedia_stream_info
#include <stream.h>

This structure describes media stream information. Each media stream corresponds to one “m=” line in SDP session descriptor, and it has its own RTP/RTCP socket pair.

Public Members

pjmedia_type type

Media type (audio, video)

pjmedia_tp_proto proto

Transport protocol (RTP/AVP, etc.)

pjmedia_dir dir

Media direction.

pj_sockaddr local_addr

Local RTP address

pj_sockaddr rem_addr

Remote RTP address

pj_sockaddr rem_rtcp

Optional remote RTCP address. If sin_family is zero, the RTP address will be calculated from RTP.

pj_bool_t rtcp_mux

Use RTP and RTCP multiplexing.

pjmedia_rtcp_fb_info loc_rtcp_fb

Local RTCP-FB info.

pjmedia_rtcp_fb_info rem_rtcp_fb

Remote RTCP-FB info.

pjmedia_codec_info fmt

Incoming codec format info.

pjmedia_codec_param *param

Optional codec param.

unsigned tx_pt

Outgoing codec paylaod type.

unsigned rx_pt

Incoming codec paylaod type.

unsigned tx_maxptime

Outgoing codec max ptime.

int tx_event_pt

Outgoing pt for telephone-events.

int rx_event_pt

Incoming pt for telephone-events.

pj_uint32_t ssrc

RTP SSRC.

pj_str_t cname

RTCP CNAME.

pj_bool_t has_rem_ssrc

Has remote RTP SSRC?

pj_uint32_t rem_ssrc

Remote RTP SSRC.

pj_str_t rem_cname

Remote RTCP CNAME.

pj_uint32_t rtp_ts

Initial RTP timestamp.

pj_uint16_t rtp_seq

Initial RTP sequence number.

pj_uint8_t rtp_seq_ts_set

Bitmask flags if initial RTP sequence and/or timestamp for sender are set. bit 0/LSB : sequence flag bit 1 : timestamp flag

int jb_init

Jitter buffer init delay in msec.

(-1 for default).

int jb_min_pre

Jitter buffer minimum prefetch delay in msec (-1 for default).

int jb_max_pre

Jitter buffer maximum prefetch delay in msec (-1 for default).

int jb_max

Jitter buffer max delay in msec.

pjmedia_jb_discard_algo jb_discard_algo

Jitter buffer discard algorithm.

pj_bool_t use_ka

Stream keep-alive and NAT hole punch (see #PJMEDIA_STREAM_ENABLE_KA) is enabled?

pjmedia_stream_ka_config ka_cfg

Stream send kep-alive settings.

pj_bool_t rtcp_sdes_bye_disabled

Disable automatic sending of RTCP SDES and BYE.

struct pjmedia_stream_dtmf_event
#include <stream.h>

This structure describes DTMF telephony-events indicated through pjmedia_stream_set_dtmf_event_callback().

Public Members

int digit

DTMF digit as ASCII character.

pj_uint32_t timestamp

RTP timestamp of the event.

pj_uint16_t duration

Event duration, in milliseconds.

pj_uint16_t flags

Event flags (see pjmedia_stream_dtmf_event_flags).