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