The Video Util APIs provides functions that transcode a media file.

Required Header

#include <video_util.h>

Overview

Video Util API provides support for transcoding of a media file. Codec and the format that the API supported :

Video : mpge4/h.263/h.264
Audio : aac/amrnb
Format : 3gp/mp4/max

Related Features

This API is related with the following features:

http://tizen.org/feature/multimedia.transcoder

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.

Foreach Operations

FOREACH	CALLBACK	DESCRIPTION
video_util_foreach_supported_file_format()	video_util_supported_file_format_cb()	Retrieves the list of supported media format
video_util_foreach_supported_video_codec()	video_util_supported_video_encoder_cb()	Retrieves the list of supported video codec
video_util_foreach_supported_audio_codec()	video_util_supported_audio_encoder_cb()	Retrieves the list of supported audio codec

Functions
int	video_util_create (video_util_h *handle)
	Creates a handle to video util.
int	video_util_destroy (video_util_h handle)
	Destroys a handle to video util.
int	video_util_set_file_path (video_util_h handle, const char *path)
	Sets the video util's file path.
int	video_util_set_accurate_mode (video_util_h handle, bool mode)
	Sets the video util's accurate mode.
int	video_util_set_video_codec (video_util_h handle, video_util_video_codec_e codec)
	Sets the video codec for encoding video stream.
int	video_util_set_audio_codec (video_util_h handle, video_util_audio_codec_e codec)
	Sets the audio codec for encoding audio stream.
int	video_util_set_file_format (video_util_h handle, video_util_file_format_e format)
	Sets the file format for transcoding media stream.
int	video_util_set_resolution (video_util_h handle, int width, int height)
	Sets the resolution(width and height).
int	video_util_set_fps (video_util_h handle, int fps)
	Sets the frame rate.
int	video_util_start_transcoding (video_util_h handle, unsigned long start, unsigned long duration, const char out_path, video_util_transcoding_progress_cb progress_cb, video_util_transcoding_completed_cb completed_cb, void user_data)
	Transcodes the video for given video util handle.
int	video_util_cancel_transcoding (video_util_h handle)
	Cancels transcoding the video for given video util handle.
int	video_util_get_progress_transcoding (video_util_h handle, unsigned long current_position, unsigned long duration)
	Retrieves the current position and duration of the video transcoding.
int	video_util_foreach_supported_file_format (video_util_h handle, video_util_supported_file_format_cb callback, void *user_data)
	Retrieves all supported media formats by invoking a specific callback for each supported media format.
int	video_util_foreach_supported_video_codec (video_util_h handle, video_util_supported_video_encoder_cb callback, void *user_data)
	Retrieves all supported video encoders by invoking a specific callback for each supported video encoder.
int	video_util_foreach_supported_audio_codec (video_util_h handle, video_util_supported_audio_encoder_cb callback, void *user_data)
	Retrieves all supported audio encoders by invoking a specific callback for each supported audio encoder.
Typedefs
typedef struct video_util_s *	video_util_h
	Video util handle.
typedef void(*	video_util_transcoding_progress_cb )(unsigned long current_position, unsigned long duration, void *user_data)
	Called regularly during the video transcoding.
typedef void(*	video_util_transcoding_completed_cb )(video_util_error_e error_code, void *user_data)
	Called when transcoding is finished just before storing in the file.
typedef bool(*	video_util_supported_file_format_cb )(video_util_file_format_e format, void *user_data)
	Called iteratively to notify you about the supported file formats.
typedef bool(*	video_util_supported_video_encoder_cb )(video_util_video_codec_e codec, void *user_data)
	Called iteratively to notify you of supported video codec.
typedef bool(*	video_util_supported_audio_encoder_cb )(video_util_audio_codec_e codec, void *user_data)
	Called iteratively to notify you about the supported audio codec.

Typedef Documentation

typedef struct video_util_s* video_util_h

Video util handle.

Since :: 2.3

typedef bool(* video_util_supported_audio_encoder_cb)(video_util_audio_codec_e codec, void *user_data)

Called iteratively to notify you about the supported audio codec.

Since :: 2.3

Parameters:

[in]	format	The codec of audio
[in]	user_data	The user data passed from the foreach function

Returns:: true to continue with the next iteration of the loop, otherwise false to break out of the loop

Precondition:: video_util_foreach_supported_audio_codec() will invoke this callback.

typedef bool(* video_util_supported_file_format_cb)(video_util_file_format_e format, void *user_data)

Called iteratively to notify you about the supported file formats.

Since :: 2.3

Parameters:

[in]	format	The format of media files
[in]	user_data	The user data passed from the foreach function

Returns:: true to continue with the next iteration of the loop, otherwise false to break out of the loop

Precondition:: video_util_foreach_supported_file_format() will invoke this callback.

typedef bool(* video_util_supported_video_encoder_cb)(video_util_video_codec_e codec, void *user_data)

Called iteratively to notify you of supported video codec.

Since :: 2.3

Parameters:

[in]	format	The codec of video
[in]	user_data	The user data passed from the foreach function

Returns:: true to continue with the next iteration of the loop, otherwise false to break out of the loop

Precondition:: video_util_foreach_supported_video_codec() will invoke this callback.

typedef void(* video_util_transcoding_completed_cb)(video_util_error_e error_code, void *user_data)

Called when transcoding is finished just before storing in the file.

Since :: 2.3

Parameters:

[in]	error_code	The error code of video util
[in]	user_data	The user data passed from the callback registration function

Precondition:: video_util_start_transcoding() will invoke this function.

typedef void(* video_util_transcoding_progress_cb)(unsigned long current_position, unsigned long duration, void *user_data)

Called regularly during the video transcoding.

Since :: 2.3

The interval of callback invocation depends on the framework.

Parameters:

[in]	current_position	The current position in milliseconds
[in]	duration	The duration in seconds
[in]	user_data	The user data passed from the callback registration function

Precondition:: This callback function is invoked if you register this callback using video_util_set_progress_transcoding_cb().

See also:: video_util_start_transcoding()

Enumeration Type Documentation

enum video_util_audio_codec_e

Enumeration for audio codec.

Since :: 2.3

Enumerator:

VIDEO_UTIL_AUDIO_CODEC_AAC	AAC
VIDEO_UTIL_AUDIO_CODEC_AMRNB	AMRNB
VIDEO_UTIL_AUDIO_CODEC_NONE	No transcoding for audio

enum video_util_error_e

Enumeration for errors of a video util.

Since :: 2.3

Enumerator:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
VIDEO_UTIL_ERROR_INVALID_OPERATION	Invalid operation
VIDEO_UTIL_ERROR_BUSY	Device or resource busy
VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

enum video_util_file_format_e

Enumeration for formats of a media.

Since :: 2.3

Enumerator:

VIDEO_UTIL_FILE_FORMAT_3GP	3GP
VIDEO_UTIL_FILE_FORMAT_MP4	MP4

enum video_util_video_codec_e

Enumeration for video codec.

Since :: 2.3

Enumerator:

VIDEO_UTIL_VIDEO_CODEC_MPEG4	MPEG4
VIDEO_UTIL_VIDEO_CODEC_H263	H.263
VIDEO_UTIL_VIDEO_CODEC_H264	H.264
VIDEO_UTIL_VIDEO_CODEC_NONE	No transcoding for video

Function Documentation

int video_util_cancel_transcoding ( video_util_h handle )

Cancels transcoding the video for given video util handle.

Since :: 2.3

This function cancels the transcoding for given video util handle.
.

Remarks:: If this function is invoked during transcoding, the data transcoded is discard.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in] handle The handle to video util

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_INVALID_OPERATION	Invalid operation
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy(); video_util_start_transcoding()

int video_util_create ( video_util_h * handle )

Creates a handle to video util.

Since :: 2.3

This function creates a handle to video util.

Remarks:: You must release the video util handle using video_util_destroy().
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[out] handle A handle to video util

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_destroy()

int video_util_destroy ( video_util_h handle )

Destroys a handle to video util.

Since :: 2.3

The function frees all resources related to the video util handle. The video util handle no longer can be used to perform any operation. A new video util handle has to be created before the next usage.

Remarks:: http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in] handle The handle to video util

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create()

int video_util_foreach_supported_audio_codec	(	video_util_h	handle,
		video_util_supported_audio_encoder_cb	callback,
		void *	user_data
	)

Retrieves all supported audio encoders by invoking a specific callback for each supported audio encoder.

Since :: 2.3

Remarks:: The callback invocation depends on the file format.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	callback	The callback function to be invoked
[in]	user_data	The user data to be passed to the callback function

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: video_util_supported_audio_encoder_cb() will be invoked.

See also:: video_util_supported_audio_encoder_cb()

int video_util_foreach_supported_file_format	(	video_util_h	handle,
		video_util_supported_file_format_cb	callback,
		void *	user_data
	)

Retrieves all supported media formats by invoking a specific callback for each supported media format.

Since :: 2.3

Remarks:: The callback invocation depends on the codec.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: video_util_supported_file_format_cb() will be invoked.

See also:: video_util_set_file_format(); video_util_supported_file_format_cb()

int video_util_foreach_supported_video_codec	(	video_util_h	handle,
		video_util_supported_video_encoder_cb	callback,
		void *	user_data
	)

Retrieves all supported video encoders by invoking a specific callback for each supported video encoder.

Since :: 2.3

Remarks:: The callback invocation depends on the file format.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	callback	The callback function to be invoked
[in]	user_data	The user data to be passed to the callback function

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: video_util_supported_video_encoder_cb() will be invoked.

See also:: video_util_set_video_codec(); video_util_supported_video_encoder_cb()

int video_util_get_progress_transcoding	(	video_util_h	handle,
		unsigned long *	current_position,
		unsigned long *	duration
	)

Retrieves the current position and duration of the video transcoding.

Since :: 2.3

Remarks:: http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[out]	current_position	Current position of transcoding
[out]	duration	The duration is in seconds. If duration is 0, transcoding happens until end of the video

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

Precondition:: video_util_start_transcoding().

See also:: video_util_create(); video_util_destroy()

int video_util_set_accurate_mode	(	video_util_h	handle,
		bool	mode
	)

Sets the video util's accurate mode.

Since :: 2.3

Remarks:: If you do not set this, the default value is false.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	mode	Set `true` if the user can get an accurated frame for given the duration in video_util_start_transcoding(), otherwise set `false` if user can only get the nearest i-frame

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy()

int video_util_set_audio_codec	(	video_util_h	handle,
		video_util_audio_codec_e	codec
	)

Sets the audio codec for encoding audio stream.

Since :: 2.3

Remarks:: You can get available list of audio codec by using video_util_foreach_supported_audio_codec().
If you do not set this, the default codec is VIDEO_UTIL_AUDIO_CODEC_AAC.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	codec	The audio codec

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy(); video_util_foreach_supported_audio_codec()

int video_util_set_file_format	(	video_util_h	handle,
		video_util_file_format_e	format
	)

Sets the file format for transcoding media stream.

Since :: 2.3

Remarks:: You can get available list of media formats by using video_util_foreach_supported_file_format().
If you do not set this, the default file format is VIDEO_UTIL_FILE_FORMAT_3GP.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	format	The media file format

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy(); video_util_foreach_supported_file_format()

int video_util_set_file_path	(	video_util_h	handle,
		const char *	path
	)

Sets the video util's file path.

Since :: 2.3

This function sets the source path to transcode.

Remarks:: http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	path	The source file path

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_OUT_OF_MEMORY	Out of memory
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied

See also:: video_util_create(); video_util_destroy()

int video_util_set_fps	(	video_util_h	handle,
		int	fps
	)

Sets the frame rate.

Since :: 2.3

Remarks:: If fps is set 0, the default is original fps from source.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	fps	The frame rate(minimum value is 5, maximum value is 30)

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy()

int video_util_set_resolution	(	video_util_h	handle,
		int	width,
		int	height
	)

Sets the resolution(width and height).

Since :: 2.3

Remarks:: If you do not set, the default resolution is original size.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	width	The media's width If the width is 0, it set original size.(minimum value is 128)
[in]	height	The media's height If the height is 0, it set original size.(minimum value is 96)

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy()

int video_util_set_video_codec	(	video_util_h	handle,
		video_util_video_codec_e	codec
	)

Sets the video codec for encoding video stream.

Since :: 2.3

Remarks:: You can get available list of video codec by using video_util_foreach_supported_video_codec().
If you do not set this, the default codec is VIDEO_UTIL_VIDEO_CODEC_MPEG4.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	codec	The video codec

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT	Not supported format
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy(); video_util_foreach_supported_video_codec()

int video_util_start_transcoding	(	video_util_h	handle,
		unsigned long	start,
		unsigned long	duration,
		const char *	out_path,
		video_util_transcoding_progress_cb	progress_cb,
		video_util_transcoding_completed_cb	completed_cb,
		void *	user_data
	)

Transcodes the video for given video util handle.

Since :: 2.3

This function starts the transcoding from start time and for given duration.
video_util_transcoding_progress_cb() function is called during the video transcoding regularly after some interval.
video_util_transcoding_completed_cb() function is called and the transcoded video will be saved at the given output path when transcoding is finished.

Remarks:: If there already exists same file in file system, then old file will be overwritten.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	handle	The handle to video util
[in]	start	The start position to transcode
[in]	duration	The duration in seconds if duration is `0`, transcoding happens until end of the video.
[out]	out_path	The file path to save
[in]	progress_cb	The callback function to be invoked
[in]	completed_cb	The callback function to be invoked
[in]	user_data	The user data to be passed to the callback function

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

Return values:

VIDEO_UTIL_ERROR_NONE	Successful
VIDEO_UTIL_ERROR_INVALID_PARAMETER	Invalid parameter
VIDEO_UTIL_ERROR_INVALID_OPERATION	Invalid operation
VIDEO_UTIL_ERROR_PERMISSION_DENIED	Permission denied
VIDEO_UTIL_ERROR_NOT_SUPPORTED	Not supported

See also:: video_util_create(); video_util_destroy(); video_util_transcoding_progress_cb(); video_util_transcoding_completed_cb(); video_util_get_progress_transcoding(); video_util_cancel_transcoding()

Required Header

Overview

Related Features

Foreach Operations

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation