include/video_util.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17
  18 #ifndef __TIZEN_MEDIA_VIDEO_UTIL_H__
  19 #define __TIZEN_MEDIA_VIDEO_UTIL_H__
  20
  21
  22 #include <video_util_type.h>
  23
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29 /**
  30  * @addtogroup CAPI_MEDIA_VIDEO_UTIL_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Creates a handle to video util.
  36  * @details This function creates a handle to video util.
  37  * @remarks The @a video util handle must be released with video_util_destroy() by you.
  38  * @param[out] handle A handle to video util
  39  * @return 0 on success, otherwise a negative error value.
  40  * @retval #VIDEO_UTIL_ERROR_NONE Successful
  41  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  42  * @retval #VIDEO_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  43  * @see video_util_destroy()
  44  *
  45  */
  46 int video_util_create(video_util_h *handle);
  47
  48 /**
  49  * @brief Destroys a handle to video util.
  50  * @details The function frees all resources related to the video util handle. The video util
  51  * handle no longer can be used to perform any operation. A new video util handle
  52  * has to be created before the next usage.
  53  *
  54  * @param[in] handle The handle to video util
  55  * @return 0 on success, otherwise a negative error value.
  56  * @retval #VIDEO_UTIL_ERROR_NONE Successful
  57  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  58  * @see video_util_create()
  59  *
  60  */
  61 int video_util_destroy(video_util_h handle);
  62
  63 /**
  64  * @brief Sets the video util's file path.
  65  * @details This function sets the @a source path to transcode.
  66  * @param[in] handle The handle to video util
  67  * @param[in] path The source file path
  68  * @return return 0 on success, otherwise a negative error value.
  69  * @retval #VIDEO_UTIL_ERROR_NONE Successful
  70  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  71  * @retval #VIDEO_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  72  * @see video_util_create()
  73  * @see video_util_destroy()
  74  */
  75 int video_util_set_file_path(video_util_h handle, const char *path);
  76
  77 /**
  78  * @brief Sets the video util's accurate mode.
  79  * @remarks If you do not set, the default value is @c false.
  80  * @param[in] handle The handle to video util
  81  * @param [in] mode @c true, user can get an accurated frame for given the duration in video_util_start_transcoding()\n
  82  * @c false, user can only get the nearest i-frame
  83  * @return return 0 on success, otherwise a negative error value.
  84  * @retval #VIDEO_UTIL_ERROR_NONE Successful
  85  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  86  * @see video_util_create()
  87  * @see video_util_destroy()
  88  */
  89 int video_util_set_accurate_mode(video_util_h handle, bool mode);
  90
  91
  92 /**
  93  * @brief  Sets the video codec for encoding video stream.
  94  * @remarks You can get available list of video codec by using video_util_foreach_supported_video_codec().\n
  95  * If you do not set, the default codec is #VIDEO_UTIL_VIDEO_CODEC_MPEG4.
  96  * @param[in] handle The handle to video util
  97  * @param[in] codec The video codec
  98  * @return 0 on success, otherwise a negative error value.
  99  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 100  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 101  * @see video_util_create()
 102  * @see video_util_destroy()
 103  * @see video_util_get_video_codec()
 104  * @see video_util_foreach_supported_video_codec()
 105  */
 106 int video_util_set_video_codec(video_util_h handle, video_util_video_codec_e codec);
 107
 108 /**
 109  * @brief  Sets the audio codec for encoding audio stream.
 110  * @remarks You can get available list of audio codec by using video_util_foreach_supported_audio_codec().\n
 111  * If you do not set, the default codec is #VIDEO_UTIL_AUDIO_CODEC_AAC.
 112  * @param[in] handle The handle to video util
 113  * @param[in] codec The audio codec
 114  * @return 0 on success, otherwise a negative error value.
 115  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 116  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 117  * @see video_util_create()
 118  * @see video_util_destroy()
 119  * @see video_util_get_audio_codec()
 120  * @see video_util_foreach_supported_audio_codec()
 121  */
 122 int video_util_set_audio_codec(video_util_h handle, video_util_audio_codec_e codec);
 123
 124 /**
 125  * @brief  Sets the file format for transcoding media stream.
 126  * @remarks You can get available list of media format by using video_util_foreach_supported_file_format().\n
 127  * If you do not set, the default file format is #VIDEO_UTIL_FILE_FORMAT_3GP.
 128  * @param[in] handle The handle to video util
 129  * @param[in] format The media file format
 130  * @return 0 on success, otherwise a negative error value.
 131  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 132  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @see video_util_create()
 134  * @see video_util_destroy()
 135  * @see video_util_get_file_format()
 136  * @see video_util_foreach_supported_file_format()
 137  */
 138 int video_util_set_file_format(video_util_h handle, video_util_file_format_e format);
 139
 140 /**
 141  * @brief Sets the resolution(width and height).
 142  * @remarks If you do not set, the default resolution is original size.
 143  * @param[in] handle The handle to video util
 144  * @param[in] width The media's width, if the width is 0, it set original size.(minimum value is 128)
 145  * @param[in] height The media's height, if the height is 0, it set original size.(minimum value is 96)
 146  * @return 0 on success, otherwise a negative error value.
 147  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 148  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 149  * @see video_util_create()
 150  * @see video_util_destroy()
 151  * @see video_util_get_resolution()
 152  */
 153 int video_util_set_resolution(video_util_h handle, int width, int height);
 154
 155 /**
 156  * @brief Sets the frame rate.
 157  * @remarks  If  fps is set 0, the default is original fps from source.
 158  * @param[in] handle The handle to video util
 159  * @param[in] fps The frame rate(minimum value is 5, maximum value is 30)
 160  * @return 0 on success, otherwise a negative error value.
 161  * @retval #VIDEO_UTIL_EROR_NONE Successful
 162  * @retval #VIDEO_UTIL_EROR_INVALID_PARAMETER Invalid parameter
 163  * @see video_util_create()
 164  * @see video_util_destroy()
 165  */
 166 int video_util_set_fps(video_util_h handle, int fps);
 167
 168 /**
 169  * @brief Transcodes the video for given video util handle.
 170  * @details This function starts the transcoding from start time and for given duration.\n
 171 #video_util_transcoding_progress_cb() function is called during the video transcoding regularly after some interval.\n
 172 #video_util_transcoding_completed_cb() function is called and the transcoded video will be saved at the given output path when transcoding is finished corresponding callback.
 173  * @remarks If there is already exists same file in file system, then old file will be overwritten.
 174  * @param[in] handle The handle to video util
 175  * @param[in] start The start position to transcode
 176  * @param[in] duration The duration is in seconds.\n
 177  If duration is 0, transcoding happens until end of the video.
 178  * @param[out] out_path The file path to save
 179  * @param[in] progress_cb The callback function to invoke
 180  * @param[in] completed_cb The callback function to invoke
 181  * @param[in] user_data The user data to be passed to the callback function
 182  * @return 0 on success, otherwise a negative error value.
 183  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 184  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 185  * @retval #VIDEO_UTIL_ERROR_INVALID_OPERATION Invalid operation
 186  * @see video_util_create()
 187  * @see video_util_destroy()
 188  * @see video_util_transcoding_progress_cb()
 189  * @see video_util_transcoding_completed_cb()
 190  * @see video_util_get_progress_transcoding()
 191  * @see video_util_cancel_transcoding()
 192  */
 193 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);
 194
 195 /**
 196  * @brief Cancels to transcode the video for given video util handle.
 197  * @details This function cancels the transcoding for given video util handle.\n
 198  * @remarks If this function is invoked during transcoding, the data transcoded is discard.
 199  * @param[in] handle The handle to video util
 200  * @return 0 on success, otherwise a negative error value.
 201  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 202  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 203  * @retval #VIDEO_UTIL_ERROR_INVALID_OPERATION Invalid operation
 204  * @see video_util_create()
 205  * @see video_util_destroy()
 206  * @see video_util_start_transcoding()
 207  */
 208 int video_util_cancel_transcoding(video_util_h handle);
 209
 210 /**
 211  * @brief Retreives the current position and duration of the video transcoding.
 212  * @param[in] handle The handle to video util
 213  * @param[out] current_position The transcoded current position
 214  * @param[out] duration The duration is in seconds.\n
 215  If duration is 0, transcoding happens until end of the video.
 216  * @return 0 on success, otherwise a negative error value.
 217  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 218  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @pre video_util_start_transcoding()
 220  * @see video_util_create()
 221  * @see video_util_destroy()
 222  */
 223 int video_util_get_progress_transcoding(video_util_h handle, unsigned long *current_position, unsigned long *duration);
 224
 225 /**
 226  * @brief  Retrieves all supported media format by invoking a specific callback for each supported media format.
 227  * @remarks The callback invocation depends on the codec.
 228  * @param[in] handle The handle to video util
 229  * @param[in] callback The callback function to invoke
 230  * @param[in] user_data The user data to be passed to the callback function
 231  * @return 0 on success, otherwise a negative error value.
 232  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 233  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 234  * @post  video_util_supported_file_format_cb() will be invoked
 235  * @see video_util_get_file_format()
 236  * @see video_util_set_file_format()
 237  * @see video_util_supported_file_format_cb()
 238  */
 239 int video_util_foreach_supported_file_format(video_util_h handle, video_util_supported_file_format_cb callback, void *user_data);
 240
 241 /**
 242  * @brief  Retrieves all supported video encoder by invoking a specific callback for each supported video encoder.
 243  * @remarks The callback invocation depends on the file format.
 244  * @param[in] handle The handle to video util
 245  * @param[in] callback The callback function to invoke
 246  * @param[in] user_data The user data to be passed to the callback function
 247  * @return 0 on success, otherwise a negative error value.
 248  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 249  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 250  * @post  video_util_supported_video_encoder_cb() will be invoked
 251  * @see video_util_get_video_codec()
 252  * @see video_util_set_video_codec()
 253  * @see video_util_supported_video_encoder_cb()
 254  */
 255 int video_util_foreach_supported_video_codec(video_util_h handle, video_util_supported_video_encoder_cb callback, void *user_data);
 256
 257 /**
 258  * @brief  Retrieves all supported audio encoder by invoking a specific callback for each supported audio encoder.
 259  * @remarks The callback invocation depends on the file format.
 260  * @param[in] handle The handle to video util
 261  * @param[in] callback The callback function to invoke
 262  * @param[in] user_data The user data to be passed to the callback function
 263  * @return 0 on success, otherwise a negative error value.
 264  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 265  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 266  * @post  video_util_supported_audio_encoder_cb() will be invoked
 267  * @see video_util_get_audio_codec()
 268  * @see video_util_set_audio_codec()
 269  * @see video_util_supported_audio_encoder_cb()
 270  */
 271 int video_util_foreach_supported_audio_codec(video_util_h handle, video_util_supported_audio_encoder_cb callback, void *user_data);
 272
 273
 274 /**
 275  * @}
 276  */
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif /* __cplusplus */
 281
 282 #endif /*__TIZEN_MEDIA_VIDEO_UTIL_H__ */