The Media Source API provides functions to manage media sources to communicate with the remote peer.

Required Header

#include <webrtc.h>

Overview

The WebRTC Media Source API allows you to:

add/remove the media source (audiotest, videotest, mic, camera, screen, media file, media packet)
pause/mute the media source
get/set the transceiver direction to the media source (sendrecv, sendonly, recvonly)
set/get the video resolution of the media source
push a media packet in case of the media packet source

Related Features

This API is related with the following features:

http://tizen.org/feature/microphone
http://tizen.org/feature/camera

It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions
int	webrtc_add_media_source (webrtc_h webrtc, webrtc_media_source_type_e type, unsigned int *source_id)
	Adds a media source.
int	webrtc_remove_media_source (webrtc_h webrtc, unsigned int source_id)
	Removes the media source.
int	webrtc_media_source_set_transceiver_direction (webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, webrtc_transceiver_direction_e direction)
	Sets the transceiver direction to the media source with specified media type.
int	webrtc_media_source_get_transceiver_direction (webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, webrtc_transceiver_direction_e *direction)
	Gets the transceiver direction of the media source with specified media type.
int	webrtc_media_source_set_pause (webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool pause)
	Sets pause to the media source.
int	webrtc_media_source_get_pause (webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool *paused)
	Gets the pause state of the media source.
int	webrtc_media_source_set_mute (webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool mute)
	Sets mute to the media source.
int	webrtc_media_source_get_mute (webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool *muted)
	Gets the mute state of the media source.
int	webrtc_media_source_set_video_resolution (webrtc_h webrtc, unsigned int source_id, int width, int height)
	Sets a video resolution to the media source.
int	webrtc_media_source_get_video_resolution (webrtc_h webrtc, unsigned int source_id, int width, int height)
	Gets the video resolution of the media source.
int	webrtc_mic_source_set_sound_stream_info (webrtc_h webrtc, unsigned int source_id, sound_stream_info_h stream_info)
	Sets the mic source's sound manager stream information.
int	webrtc_media_packet_source_set_buffer_state_changed_cb (webrtc_h webrtc, unsigned int source_id, webrtc_media_packet_source_buffer_state_changed_cb callback, void *user_data)
	Sets a callback function to be invoked when the buffer state of media packet source is changed.
int	webrtc_media_packet_source_unset_buffer_state_changed_cb (webrtc_h webrtc, unsigned int source_id)
	Unsets the buffer state changed callback function.
int	webrtc_media_packet_source_set_format (webrtc_h webrtc, unsigned int source_id, media_format_h format)
	Sets media format to the media packet source.
int	webrtc_media_packet_source_push_packet (webrtc_h webrtc, unsigned int source_id, media_packet_h packet)
	Pushes media packet to the media packet source.
Typedefs
typedef void(*	webrtc_media_packet_source_buffer_state_changed_cb )(unsigned int source_id, webrtc_media_packet_source_buffer_state_e state, void *user_data)
	Called when the buffer state of media packet source is changed.

Typedef Documentation

typedef void(* webrtc_media_packet_source_buffer_state_changed_cb)(unsigned int source_id, webrtc_media_packet_source_buffer_state_e state, void *user_data)

Called when the buffer state of media packet source is changed.

Since :: 6.5

Parameters:

[in]	source_id	The media source id
[in]	state	The buffer state (underflow or overflow)
[in]	user_data	The user data passed from the callback registration function

See also:: webrtc_media_packet_source_set_buffer_state_changed_cb(); webrtc_media_packet_source_unset_buffer_state_changed_cb()

Enumeration Type Documentation

enum webrtc_media_packet_source_buffer_state_e

Enumeration for buffer state type of media packet source.

Since :: 6.5

Enumerator:

WEBRTC_MEDIA_PACKET_SOURCE_BUFFER_STATE_UNDERFLOW	Buffer underflow
WEBRTC_MEDIA_PACKET_SOURCE_BUFFER_STATE_OVERFLOW	Buffer overflow

enum webrtc_media_source_type_e

Enumeration for WebRTC media source type.

Since :: 6.5

Enumerator:

WEBRTC_MEDIA_SOURCE_TYPE_AUDIOTEST	Audio test
WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST	Video test
WEBRTC_MEDIA_SOURCE_TYPE_MIC	Audio from microphone
WEBRTC_MEDIA_SOURCE_TYPE_CAMERA	Camera preview
WEBRTC_MEDIA_SOURCE_TYPE_SCREEN	Screen capture
WEBRTC_MEDIA_SOURCE_TYPE_FILE	Media file
WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET	Media packet

enum webrtc_transceiver_direction_e

Enumeration for WebRTC transceiver direction type.

Since :: 6.5

Enumerator:

WEBRTC_TRANSCEIVER_DIRECTION_SENDONLY	Send only
WEBRTC_TRANSCEIVER_DIRECTION_RECVONLY	Receive only
WEBRTC_TRANSCEIVER_DIRECTION_SENDRECV	Send and receive

Function Documentation

int webrtc_add_media_source	(	webrtc_h	webrtc,
		webrtc_media_source_type_e	type,
		unsigned int *	source_id
	)

Adds a media source.

Since :: 6.5

Remarks:: The camera privilege(http://tizen.org/privilege/camera) should be added if type is WEBRTC_MEDIA_SOURCE_TYPE_CAMERA.
The recorder privilege(http://tizen.org/privilege/recorder) should be added if type is WEBRTC_MEDIA_SOURCE_TYPE_MIC.

Parameters:

[in]	webrtc	WebRTC handle
[in]	type	The media source type to be added
[out]	source_id	The media source id

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_NOT_SUPPORTED	Not supported
WEBRTC_ERROR_PERMISSION_DENIED	Permission denied
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: webrtc_remove_media_source(); webrtc_media_source_set_transceiver_direction(); webrtc_media_source_get_transceiver_direction(); webrtc_media_source_set_pause(); webrtc_media_source_get_pause(); webrtc_media_source_set_mute(); webrtc_media_source_get_mute(); webrtc_media_source_set_video_resolution(); webrtc_media_source_get_video_resolution(); webrtc_media_packet_source_set_buffer_state_changed_cb(); webrtc_media_packet_source_unset_buffer_state_changed_cb(); webrtc_media_packet_source_set_format(); webrtc_media_packet_source_push_packet()

int webrtc_media_packet_source_push_packet	(	webrtc_h	webrtc,
		unsigned int	source_id,
		media_packet_h	packet
	)

Pushes media packet to the media packet source.

Since :: 6.5

Remarks:: This function takes ownership of the packet.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media packet source id
[in]	packet	The media packet

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Add media packet source to webrtc to get source_id by calling webrtc_add_media_source().; webrtc_media_packet_source_set_format() must be called before calling this function.; webrtc_media_packet_source_buffer_state_changed_cb() must be set by calling webrtc_media_packet_source_set_buffer_state_changed_cb().

See also:: webrtc_media_packet_source_set_format(); webrtc_media_packet_source_set_buffer_state_changed_cb()

int webrtc_media_packet_source_set_buffer_state_changed_cb	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_packet_source_buffer_state_changed_cb	callback,
		void *	user_data
	)

Sets a callback function to be invoked when the buffer state of media packet source is changed.

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media packet source id
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Add media packet source to webrtc to get source_id by calling webrtc_add_media_source().

Postcondition:: webrtc_media_packet_source_buffer_state_changed_cb() will be invoked.

See also:: webrtc_media_packet_source_push_packet(); webrtc_media_packet_source_unset_buffer_state_changed_cb(); webrtc_media_packet_source_buffer_state_changed_cb()

int webrtc_media_packet_source_set_format	(	webrtc_h	webrtc,
		unsigned int	source_id,
		media_format_h	format
	)

Sets media format to the media packet source.

Since :: 6.5

Remarks:: The following media format mimetypes can be used to create the format :
MEDIA_FORMAT_VORBIS
MEDIA_FORMAT_OPUS
MEDIA_FORMAT_PCM_S16LE
MEDIA_FORMAT_PCMU
MEDIA_FORMAT_PCMA
MEDIA_FORMAT_H264_SP
MEDIA_FORMAT_H264_MP
MEDIA_FORMAT_H264_HP
MEDIA_FORMAT_MJPEG
MEDIA_FORMAT_VP8
MEDIA_FORMAT_VP9
MEDIA_FORMAT_I420
MEDIA_FORMAT_NV12
For more details, please refer to Media Format.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media packet source id
[in]	format	The media format

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: Add media packet source to webrtc to get source_id by calling webrtc_add_media_source().; webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: webrtc_media_packet_source_push_packet(); webrtc_media_packet_source_set_buffer_state_changed_cb()

int webrtc_media_packet_source_unset_buffer_state_changed_cb	(	webrtc_h	webrtc,
		unsigned int	source_id
	)

Unsets the buffer state changed callback function.

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media packet source id

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Add media packet source to webrtc to get source_id by calling webrtc_add_media_source().

See also:: webrtc_media_packet_source_set_buffer_state_changed_cb()

int webrtc_media_source_get_mute	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_type_e	media_type,
		bool *	muted
	)

Gets the mute state of the media source.

If source_id is a media source of WEBRTC_MEDIA_SOURCE_TYPE_FILE or WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET, this function will return WEBRTC_ERROR_INVALID_PARAMETER.

Since :: 6.5

Remarks:: The default value is false.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id
[in]	media_type	The media type
[out]	muted	Muted or not (`true` = muted, `false` = not muted)

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_media_source_set_mute()

int webrtc_media_source_get_pause	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_type_e	media_type,
		bool *	paused
	)

Gets the pause state of the media source.

Since :: 6.5

Remarks:: The default value is false.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id
[in]	media_type	The media type
[out]	paused	Paused or not (`true` = paused, `false` = playing)

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_media_source_set_pause()

int webrtc_media_source_get_transceiver_direction	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_type_e	media_type,
		webrtc_transceiver_direction_e *	direction
	)

Gets the transceiver direction of the media source with specified media type.

Since :: 6.5

Remarks:: The default value is WEBRTC_TRANSCEIVER_DIRECTION_SENDRECV.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id
[in]	media_type	The media type
[out]	direction	Current transceiver direction

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Add media source to webrtc to get source_id by calling webrtc_add_media_source().; webrtc_media_packet_source_set_format() must be called if source_id is a media source of WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET.

See also:: webrtc_media_source_set_transceiver_direction()

int webrtc_media_source_get_video_resolution	(	webrtc_h	webrtc,
		unsigned int	source_id,
		int *	width,
		int *	height
	)

Gets the video resolution of the media source.

The following media source types contain video:
WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST
WEBRTC_MEDIA_SOURCE_TYPE_CAMERA
WEBRTC_MEDIA_SOURCE_TYPE_SCREEN

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The video source id
[out]	width	The video width
[out]	height	The video height

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Add media source to webrtc to get source_id by calling webrtc_add_media_source().

See also:: webrtc_media_source_set_video_resolution()

int webrtc_media_source_set_mute	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_type_e	media_type,
		bool	mute
	)

Sets mute to the media source.

If mute is set to true, black frame or silent sound will be transmitted to the remote peer according to the media type of the source_id.
if source_id is a media source of WEBRTC_MEDIA_SOURCE_TYPE_FILE or WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET, this function will return WEBRTC_ERROR_INVALID_PARAMETER.

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id
[in]	media_type	The media type
[in]	mute	Mute or not (`true` = mute, `false` = not mute)

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_media_source_get_mute()

int webrtc_media_source_set_pause	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_type_e	media_type,
		bool	pause
	)

Sets pause to the media source.

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id
[in]	media_type	The media type
[in]	pause	Pause or play (`true` = pause, `false` = play)

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

See also:: webrtc_media_source_get_pause()

int webrtc_media_source_set_transceiver_direction	(	webrtc_h	webrtc,
		unsigned int	source_id,
		webrtc_media_type_e	media_type,
		webrtc_transceiver_direction_e	direction
	)

Sets the transceiver direction to the media source with specified media type.

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id
[in]	media_type	The media type
[in]	direction	The transceiver direction to set

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: Add media source to webrtc to get source_id by calling webrtc_add_media_source().; webrtc_media_packet_source_set_format() must be called if source_id is a media source of WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET.; webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: webrtc_media_source_get_transceiver_direction()

int webrtc_media_source_set_video_resolution	(	webrtc_h	webrtc,
		unsigned int	source_id,
		int	width,
		int	height
	)

Sets a video resolution to the media source.

The following media source types contain video:
WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST
WEBRTC_MEDIA_SOURCE_TYPE_CAMERA
WEBRTC_MEDIA_SOURCE_TYPE_SCREEN

Since :: 6.5

Remarks:: If source_id does not support for the dynamic resolution change, WEBRTC_ERROR_INVALID_OPERATION will be returned
while webrtc state is WEBRTC_STATE_NEGOTIATING or WEBRTC_STATE_PLAYING.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The video source id
[in]	width	The video width
[in]	height	The video height

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation

Precondition:: Add media source to webrtc to get source_id by calling webrtc_add_media_source().

See also:: webrtc_media_source_get_video_resolution()

int webrtc_mic_source_set_sound_stream_info	(	webrtc_h	webrtc,
		unsigned int	source_id,
		sound_stream_info_h	stream_info
	)

Sets the mic source's sound manager stream information.

If source_id is not a media source of WEBRTC_MEDIA_SOURCE_TYPE_MIC, this function will return WEBRTC_ERROR_INVALID_PARAMETER.

Since :: 6.5

Remarks:: You can set sound stream information including audio routing.
The following sound stream types can be used to create the stream_info :
SOUND_STREAM_TYPE_MEDIA
SOUND_STREAM_TYPE_VOICE_RECOGNITION
SOUND_STREAM_TYPE_VOIP
SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY
For more details, please refer to Sound Manager.

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The mic source id
[in]	stream_info	The sound stream information

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: sound_stream_info_h; sound_manager_create_stream_information(); sound_manager_destroy_stream_information()

int webrtc_remove_media_source	(	webrtc_h	webrtc,
		unsigned int	source_id
	)

Removes the media source.

Since :: 6.5

Parameters:

[in]	webrtc	WebRTC handle
[in]	source_id	The media source id to be removed

Returns:: 0 on success, otherwise a negative error value

Return values:

WEBRTC_ERROR_NONE	Successful
WEBRTC_ERROR_INVALID_PARAMETER	Invalid parameter
WEBRTC_ERROR_INVALID_OPERATION	Invalid operation
WEBRTC_ERROR_INVALID_STATE	Invalid state

Precondition:: Add media source to webrtc to get source_id by calling webrtc_add_media_source().; webrtc state must be set to WEBRTC_STATE_IDLE.

See also:: webrtc_add_media_source()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation