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 #ifndef __TIZEN_MEDIA_VIDEO_UTIL_H__
  18 #define __TIZEN_MEDIA_VIDEO_UTIL_H__
  19
  20 #include <video_util_type.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif /* __cplusplus */
  25
  26 /**
  27  * @file video_util.h
  28  */
  29
  30 /**
  31  * @addtogroup CAPI_MEDIA_VIDEO_UTIL_MODULE
  32  * @{
  33  */
  34
  35 /**
  36  * @brief Creates a handle to video util.
  37  * @since_tizen 2.3
  38  *
  39  * @details This function creates a handle to video util.
  40  *
  41  * @remarks You must release the @a video util handle using video_util_destroy().\n
  42  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
  43  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
  44  *
  45  * @param[out] handle A handle to video util
  46  *
  47  * @return @c 0 on success,
  48  *               otherwise a negative error value
  49  *
  50  * @retval #VIDEO_UTIL_ERROR_NONE Successful
  51  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  52  * @retval #VIDEO_UTIL_ERROR_OUT_OF_MEMORY Out of memory
  53  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
  54  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
  55  *
  56  * @see video_util_destroy()
  57  *
  58  */
  59 int video_util_create(video_util_h *handle);
  60
  61 /**
  62  * @brief Destroys a handle to video util.
  63  * @since_tizen 2.3
  64  *
  65  * @details The function frees all resources related to the video util handle. The video util
  66  *               handle no longer can be used to perform any operation. A new video util handle
  67  *               has to be created before the next usage.
  68  *
  69  * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
  70  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
  71  *
  72  * @param[in] handle The handle to video util
  73  *
  74  * @return @c 0 on success,
  75  *               otherwise a negative error value
  76  *
  77  * @retval #VIDEO_UTIL_ERROR_NONE Successful
  78  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
  79  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
  80  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
  81  *
  82  * @see video_util_create()
  83  *
  84  */
  85 int video_util_destroy(video_util_h handle);
  86
  87 /**
  88  * @brief Sets the video util's file path.
  89  * @since_tizen 2.3
  90  *
  91  * @details This function sets the source @a path to transcode.
  92  *
  93  * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
  94  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
  95  *
  96  * @param[in] handle The handle to video util
  97  * @param[in] path The source file path
  98  *
  99  * @return @c 0 on success,
 100  *               otherwise a negative error value
 101  *
 102  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 103  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 104  * @retval #VIDEO_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 105  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 106  *
 107  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 108  *
 109  * @see video_util_create()
 110  * @see video_util_destroy()
 111  */
 112 int video_util_set_file_path(video_util_h handle, const char *path);
 113
 114 /**
 115  * @brief Sets the video util's accurate mode.
 116  * @since_tizen 2.3
 117  *
 118  * @remarks If you do not set this, the default value is @c false.\n
 119  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 120  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 121  *
 122  * @param[in] handle The handle to video util
 123  * @param[in] mode Set @c true if the user can get an accurated frame for given the duration in video_util_start_transcoding(),
 124  *                              otherwise set @c false if user can only get the nearest i-frame
 125  *
 126  * @return @c 0 on success,
 127  *               otherwise a negative error value
 128  *
 129  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 130  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 132  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 133  *
 134  * @see video_util_create()
 135  * @see video_util_destroy()
 136  */
 137 int video_util_set_accurate_mode(video_util_h handle, bool mode);
 138
 139 /**
 140  * @brief Sets the video codec for encoding video stream.
 141  * @since_tizen 2.3
 142  *
 143  * @remarks You can get available list of video codec by using video_util_foreach_supported_video_codec().\n
 144  *                 If you do not set this, the default codec is #VIDEO_UTIL_VIDEO_CODEC_MPEG4.\n
 145  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 146  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 147  *
 148  * @param[in] handle The handle to video util
 149  * @param[in] codec The video codec
 150  *
 151  * @return @c 0 on success,
 152  *               otherwise a negative error value
 153  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 154  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 155  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 156  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 157  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 158  *
 159  * @see video_util_create()
 160  * @see video_util_destroy()
 161  * @see video_util_foreach_supported_video_codec()
 162  */
 163 int video_util_set_video_codec(video_util_h handle, video_util_video_codec_e codec);
 164
 165 /**
 166  * @brief Sets the audio codec for encoding audio stream.
 167  * @since_tizen 2.3
 168  *
 169  * @remarks You can get available list of audio codec by using video_util_foreach_supported_audio_codec().\n
 170  *                  If you do not set this, the default codec is #VIDEO_UTIL_AUDIO_CODEC_AAC.\n
 171  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 172  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 173  *
 174  * @param[in] handle The handle to video util
 175  * @param[in] codec The audio codec
 176  *
 177  * @return @c 0 on success,
 178  *               otherwise a negative error value
 179  *
 180  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 181  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 183  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 184  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 185  *
 186  * @see video_util_create()
 187  * @see video_util_destroy()
 188  * @see video_util_foreach_supported_audio_codec()
 189  */
 190 int video_util_set_audio_codec(video_util_h handle, video_util_audio_codec_e codec);
 191
 192 /**
 193  * @brief Sets the file format for transcoding media stream.
 194  * @since_tizen 2.3
 195  *
 196  * @remarks You can get available list of media formats by using video_util_foreach_supported_file_format().\n
 197  *                 If you do not set this, the default file format is #VIDEO_UTIL_FILE_FORMAT_3GP.\n
 198  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 199  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 200  *
 201  * @param[in] handle The handle to video util
 202  * @param[in] format The media file format
 203  *
 204  * @return @c 0 on success,
 205  *               otherwise a negative error value
 206  *
 207  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 208  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 209  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 210  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 211  *
 212  * @see video_util_create()
 213  * @see video_util_destroy()
 214  * @see video_util_foreach_supported_file_format()
 215  */
 216 int video_util_set_file_format(video_util_h handle, video_util_file_format_e format);
 217
 218 /**
 219  * @brief Sets the resolution(width and height).
 220  * @since_tizen 2.3
 221  *
 222  * @remarks If you do not set, the default resolution is original size.\n
 223  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 224  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 225  *
 226  * @param[in] handle The handle to video util
 227  * @param[in] width The media's width \n
 228  *                              If the width is 0, it set original size.(minimum value is 128)
 229  * @param[in] height The media's height \n
 230  *                    If the height is 0, it set original size.(minimum value is 96)
 231  *
 232  * @return @c 0 on success,
 233  *               otherwise a negative error value
 234  *
 235  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 236  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 237  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 238  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 239  *
 240  * @see video_util_create()
 241  * @see video_util_destroy()
 242  */
 243 int video_util_set_resolution(video_util_h handle, int width, int height);
 244
 245 /**
 246  * @brief Sets the frame rate.
 247  * @since_tizen 2.3
 248  *
 249  * @remarks If fps is set @c 0, the default is original fps from source.\n
 250  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 251  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 252  *
 253  * @param[in] handle The handle to video util
 254  *
 255  * @param[in] fps The frame rate(minimum value is 5, maximum value is 30)
 256  * @return @c 0 on success,
 257  *               otherwise a negative error value
 258  *
 259  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 260  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 261  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 262  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 263  *
 264  * @see video_util_create()
 265  * @see video_util_destroy()
 266  */
 267 int video_util_set_fps(video_util_h handle, int fps);
 268
 269 /**
 270  * @brief Transcodes the video for given video util handle.
 271  * @since_tizen 2.3
 272  *
 273  * @details This function starts the transcoding from start time and for given duration.\n
 274  *              #video_util_transcoding_progress_cb() function is called during the video transcoding regularly after some interval.\n
 275  *              #video_util_transcoding_completed_cb() function is called and the transcoded video will be saved at the given output path when transcoding is finished.
 276  *
 277  * @remarks If there already exists same file in file system, then old file will be overwritten.\n
 278  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 279  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 280  *
 281  * @param[in] handle The handle to video util
 282  * @param[in] start The start position to transcode
 283  * @param[in] duration The duration in seconds \n
 284  *                                  if duration is @c 0, transcoding happens until end of the video.
 285  * @param[out] out_path The file path to save
 286  * @param[in] progress_cb The callback function to be invoked
 287  * @param[in] completed_cb The callback function to be invoked
 288  * @param[in] user_data The user data to be passed to the callback function
 289  *
 290  * @return @c 0 on success,
 291  *               otherwise a negative error value
 292  *
 293  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 294  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval #VIDEO_UTIL_ERROR_INVALID_OPERATION Invalid operation
 296  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 297  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 298  *
 299  * @see video_util_create()
 300  * @see video_util_destroy()
 301  * @see video_util_transcoding_progress_cb()
 302  * @see video_util_transcoding_completed_cb()
 303  * @see video_util_get_progress_transcoding()
 304  * @see video_util_cancel_transcoding()
 305  */
 306 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);
 307
 308 /**
 309  * @brief Cancels transcoding the video for given video util handle.
 310  * @since_tizen 2.3
 311
 312  *
 313  * @details This function cancels the transcoding for given video util handle.\n.
 314  *
 315  * @remarks If this function is invoked during transcoding, the data transcoded is discard.\n
 316  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 317  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 318  *
 319  * @param[in] handle The handle to video util
 320  *
 321  * @return @c 0 on success,
 322  *               otherwise a negative error value
 323  *
 324  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 325  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 326  * @retval #VIDEO_UTIL_ERROR_INVALID_OPERATION Invalid operation
 327  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 328  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 329  *
 330  * @see video_util_create()
 331  * @see video_util_destroy()
 332  * @see video_util_start_transcoding()
 333  */
 334 int video_util_cancel_transcoding(video_util_h handle);
 335
 336 /**
 337  * @brief Retreives the current position and duration of the video transcoding.
 338  * @since_tizen 2.3
 339
 340  *
 341  * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 342  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 343  *
 344  * @param[in] handle The handle to video util
 345  * @param[out] current_position Current position of transcoding
 346  * @param[out] duration The duration is in seconds.\n
 347  If duration is 0, transcoding happens until end of the video
 348  *
 349  * @return @c 0 on success,
 350  *               otherwise a negative error value
 351  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 352  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 353  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 354  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 355  *
 356  * @pre video_util_start_transcoding().
 357  *
 358  * @see video_util_create()
 359  * @see video_util_destroy()
 360  */
 361 int video_util_get_progress_transcoding(video_util_h handle, unsigned long *current_position, unsigned long *duration);
 362
 363 /**
 364  * @brief Retrieves all supported media formats by invoking a specific callback for each supported media format.
 365  * @since_tizen 2.3
 366  *
 367  * @remarks The callback invocation depends on the codec.\n
 368  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 369  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 370  *
 371  * @param[in] handle The handle to video util
 372  * @param[in] callback The callback function to invoke
 373  * @param[in] user_data The user data to be passed to the callback function
 374  *
 375  * @return @c 0 on success,
 376  *               otherwise a negative error value
 377  *
 378  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 379  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 380  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 381  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 382  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 383  * @post  video_util_supported_file_format_cb() will be invoked.
 384  *
 385  * @see video_util_set_file_format()
 386  * @see video_util_supported_file_format_cb()
 387  */
 388 int video_util_foreach_supported_file_format(video_util_h handle, video_util_supported_file_format_cb callback, void *user_data);
 389
 390 /**
 391  * @brief Retrieves all supported video encoders by invoking a specific callback for each supported video encoder.
 392  * @since_tizen 2.3
 393  *
 394  * @remarks The callback invocation depends on the file format.\n
 395  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 396  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 397  *
 398  * @param[in] handle The handle to video util
 399  * @param[in] callback The callback function to be invoked
 400  * @param[in] user_data The user data to be passed to the callback function
 401  *
 402  * @return @c 0 on success,
 403  *               otherwise a negative error value
 404  *
 405  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 406  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 407  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 408  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 409  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 410  * @post  video_util_supported_video_encoder_cb() will be invoked.
 411  * @see video_util_set_video_codec()
 412  * @see video_util_supported_video_encoder_cb()
 413  */
 414 int video_util_foreach_supported_video_codec(video_util_h handle, video_util_supported_video_encoder_cb callback, void *user_data);
 415
 416 /**
 417  * @brief Retrieves all supported audio encoders by invoking a specific callback for each supported audio encoder.
 418  * @since_tizen 2.3
 419  *
 420  * @remarks The callback invocation depends on the file format.\n
 421  *                 http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 422  *                 http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.\n
 423  *
 424  * @param[in] handle The handle to video util
 425  * @param[in] callback The callback function to be invoked
 426  * @param[in] user_data The user data to be passed to the callback function
 427  *
 428  * @return @c 0 on success,
 429  *               otherwise a negative error value
 430  *
 431  * @retval #VIDEO_UTIL_ERROR_NONE Successful
 432  * @retval #VIDEO_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 433  * @retval #VIDEO_UTIL_ERROR_PERMISSION_DENIED Permission denied
 434  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 435  * @retval #VIDEO_UTIL_ERROR_NOT_SUPPORTED Not supported
 436  * @post  video_util_supported_audio_encoder_cb() will be invoked.
 437  * @see video_util_supported_audio_encoder_cb()
 438  */
 439 int video_util_foreach_supported_audio_codec(video_util_h handle, video_util_supported_audio_encoder_cb callback, void *user_data);
 440
 441 /**
 442  * @}
 443  */
 444
 445 #ifdef __cplusplus
 446 }
 447 #endif /* __cplusplus */
 448
 449 #endif /* __TIZEN_MEDIA_VIDEO_UTIL_H__ */