include/streamrecorder.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_STREAMRECORDER_H__
  18 #define __TIZEN_MEDIA_STREAMRECORDER_H__
  19
  20 #include <tizen.h>
  21 #include <media_packet.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file streamrecorder.h
  29  * @brief This file contains the Streamrecorder API, related structures and enumerations.
  30  * @since_tizen 3.0
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_MEDIA_STREAMRECORDER_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief The Streamrecorder handle.
  40  * @since_tizen 3.0
  41  */
  42 typedef struct streamrecorder_s *streamrecorder_h;
  43
  44 /**
  45  * @brief Enumeration for the source type.
  46  * @since_tizen 3.0
  47  */
  48 typedef enum {
  49         STREAMRECORDER_SOURCE_VIDEO,           /**< Video only */
  50         STREAMRECORDER_SOURCE_AUDIO,           /**< Audio only */
  51         STREAMRECORDER_SOURCE_VIDEO_AUDIO,     /**< Video and Audio */
  52 } streamrecorder_source_e;
  53
  54 /**
  55  * @brief Enumeration for the pixel format.
  56  * @since_tizen 3.0
  57  */
  58 typedef enum {
  59         STREAMRECORDER_VIDEO_SOURCE_FORMAT_INVALID = -1,   /**< Invalid pixel format */
  60         STREAMRECORDER_VIDEO_SOURCE_FORMAT_NV12,           /**< NV12 pixel format */
  61         STREAMRECORDER_VIDEO_SOURCE_FORMAT_NV21,           /**< NV21 pixel format */
  62         STREAMRECORDER_VIDEO_SOURCE_FORMAT_I420,           /**< I420 pixel format */
  63         STREAMRECORDER_VIDEO_SOURCE_FORMAT_NUM             /**< @deprecated Number of the video source format (Deprecated since 6.0, please don't use it) */
  64 } streamrecorder_video_source_format_e;
  65
  66 /**
  67  * @brief Enumeration for the file container format.
  68  * @since_tizen 3.0
  69  */
  70 typedef enum {
  71         STREAMRECORDER_FILE_FORMAT_3GP,    /**< 3GP file format */
  72         STREAMRECORDER_FILE_FORMAT_MP4,    /**< MP4 file format */
  73         STREAMRECORDER_FILE_FORMAT_AMR,    /**< AMR file format */
  74         STREAMRECORDER_FILE_FORMAT_ADTS,   /**< ADTS file format */
  75         STREAMRECORDER_FILE_FORMAT_WAV,    /**< WAV file format */
  76 } streamrecorder_file_format_e;
  77
  78 /**
  79  * @brief Enumeration for the audio codec.
  80  * @since_tizen 3.0
  81  */
  82 typedef enum {
  83         STREAMRECORDER_AUDIO_CODEC_AMR = 0,      /**< AMR codec */
  84         STREAMRECORDER_AUDIO_CODEC_AAC,          /**< AAC codec */
  85         STREAMRECORDER_AUDIO_CODEC_PCM           /**< PCM codec */
  86 } streamrecorder_audio_codec_e;
  87
  88 /**
  89  * @brief Enumeration for the video codec.
  90  * @since_tizen 3.0
  91  */
  92 typedef enum {
  93         STREAMRECORDER_VIDEO_CODEC_H263,    /**< H263 codec */
  94         STREAMRECORDER_VIDEO_CODEC_MPEG4,   /**< MPEG4 codec */
  95 } streamrecorder_video_codec_e;
  96
  97 /**
  98  * @brief Enumeration for the recording limit reached.
  99  * @since_tizen 3.0
 100  */
 101 typedef enum {
 102         STREAMRECORDER_RECORDING_LIMIT_TYPE_TIME,        /**< Time limit (second) of recording file */
 103         STREAMRECORDER_RECORDING_LIMIT_TYPE_SIZE,        /**< Size limit (kilo bytes [KB]) of recording file */
 104 } streamrecorder_recording_limit_type_e;
 105
 106 /**
 107  * @brief Enumeration for Streamrecorder error type.
 108  * @since_tizen 3.0
 109  */
 110 typedef enum {
 111         STREAMRECORDER_ERROR_NONE                  = TIZEN_ERROR_NONE,                /**< Successful */
 112         STREAMRECORDER_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
 113         STREAMRECORDER_ERROR_INVALID_STATE         = TIZEN_ERROR_STREAMRECORDER | 0x01,     /**< Invalid state */
 114         STREAMRECORDER_ERROR_OUT_OF_MEMORY         = TIZEN_ERROR_OUT_OF_MEMORY ,      /**< Out of memory */
 115         STREAMRECORDER_ERROR_INVALID_OPERATION     = TIZEN_ERROR_INVALID_OPERATION,   /**< Internal error */
 116         STREAMRECORDER_ERROR_OUT_OF_STORAGE        = TIZEN_ERROR_STREAMRECORDER | 0x02,     /**< Out of storage */
 117         STREAMRECORDER_ERROR_PERMISSION_DENIED     = TIZEN_ERROR_PERMISSION_DENIED,   /**< The access to the resources can not be granted */
 118         STREAMRECORDER_ERROR_NOT_SUPPORTED         = TIZEN_ERROR_NOT_SUPPORTED,       /**< The feature is not supported */
 119 } streamrecorder_error_e;
 120
 121 /**
 122  * @brief Enumeration for the Streamrecorder notification.
 123  * @since_tizen 3.0
 124  */
 125 typedef enum {
 126         STREAMRECORDER_NOTIFY_NONE = 0,       /**< None */
 127         STREAMRECORDER_NOTIFY_STATE_CHANGED,          /**< The notification of normal state changes */
 128 } streamrecorder_notify_e;
 129
 130 /**
 131  * @brief Enumeration for Streamrecorder states.
 132  * @since_tizen 3.0
 133  */
 134 typedef enum {
 135         STREAMRECORDER_STATE_NONE,      /**< StreamRecorder is not created */
 136         STREAMRECORDER_STATE_CREATED,   /**< StreamRecorder is created, but not prepared */
 137         STREAMRECORDER_STATE_PREPARED,     /**< StreamRecorder is prepared to record */
 138         STREAMRECORDER_STATE_RECORDING, /**< StreamRecorder is recording media */
 139         STREAMRECORDER_STATE_PAUSED,    /**< StreamRecorder is paused while recording media */
 140 } streamrecorder_state_e;
 141
 142 /**
 143  * @brief Enumeration for StreamRecorder recoding modes.
 144  * @since_tizen 6.0
 145  */
 146 typedef enum {
 147         STREAMRECORDER_MODE_STREAM_BUFFER = 0,    /**< Recording with media buffer */
 148         STREAMRECORDER_MODE_DEVICE_LOOPBACK          /**< Recording with device's own screen and audio */
 149 } streamrecorder_mode_e;
 150
 151 /**
 152  * @}
 153  */
 154
 155 /**
 156  * @addtogroup CAPI_MEDIA_STREAMRECORDER_CALLBACK_MODULE
 157  * @{
 158  */
 159
 160 /**
 161  * @brief Called when limitation error occurs while recording.
 162  * @details The callback function is possible to receive three types of limits: time and size.
 163  * @since_tizen 3.0
 164  * @remarks After being called, recording data except present recorded data will be discarded and not written in the recording file. Also the state of streamrecorder is not changed.
 165  * @param[in] type The imitation type
 166  * @param[in] user_data The user data passed from the callback registration function
 167  * @pre You have to register a callback using streamrecorder_set_recording_limit_reached_cb().
 168  * @see streamrecorder_set_recording_status_cb()
 169  * @see streamrecorder_set_recording_limit_reached_cb()
 170  * @see streamrecorder_unset_recording_limit_reached_cb()
 171  */
 172 typedef void (*streamrecorder_recording_limit_reached_cb)(streamrecorder_recording_limit_type_e type, void *user_data);
 173
 174 /**
 175  * @brief Called to indicate the recording status.
 176  * @since_tizen 3.0
 177  * @remarks This callback function is repeatedly invoked during the #STREAMRECORDER_STATE_RECORDING state.
 178  * @param[in] elapsed_time  The time of the recording (milliseconds)
 179  * @param[in] file_size     The size of the recording file (KB)
 180  * @param[in] user_data     The user data passed from the callback registration function
 181  * @pre streamrecorder_start() will invoke this callback if you register it using streamrecorder_set_recording_status_cb().
 182  * @see streamrecorder_set_recording_status_cb()
 183  * @see streamrecorder_unset_recording_status_cb()
 184  * @see streamrecorder_start()
 185  */
 186 typedef void (*streamrecorder_recording_status_cb)(unsigned long long elapsed_time, unsigned long long file_size, void *user_data);
 187
 188 /**
 189  * @brief Called when the streamrecorder gets some notifications.
 190  * @since_tizen 3.0
 191  * @param[in] previous  The previous state of the streamrecorder
 192  * @param[in] current   The current state of the streamrecorder
 193  * @param[in] notification  The notification type of the streamrecorder
 194  * @param[in] user_data The user data passed from the callback registration function
 195  * @pre This function is required to register a callback using streamrecorder_set_notify_cb().
 196  * @see streamrecorder_set_notify_cb()
 197  * @see streamrecorder_prepare()
 198  * @see streamrecorder_unprepare()
 199  * @see streamrecorder_start()
 200  * @see streamrecorder_pause()
 201  * @see streamrecorder_commit()
 202  * @see streamrecorder_cancel()
 203  */
 204 typedef void (*streamrecorder_notify_cb)(streamrecorder_state_e previous, streamrecorder_state_e current, streamrecorder_notify_e notification, void *user_data);
 205
 206 /**
 207  * @brief Called when the error occurred.
 208  * @since_tizen 3.0
 209  * @remarks This callback informs about the critical error situation. \n
 210  *          When being invoked, user should release the resource and terminate the application. \n
 211  *          This error code will be reported. \n
 212  *          #STREAMRECORDER_ERROR_INVALID_OPERATION \n
 213  *          #STREAMRECORDER_ERROR_OUT_OF_MEMORY
 214  * @param[in] error          The error code
 215  * @param[in] current_state  The current state of the streamrecorder
 216  * @param[in] user_data      The user data passed from the callback registration function
 217  * @pre This callback function is invoked if you register this callback using streamrecorder_set_error_cb().
 218  * @see streamrecorder_set_error_cb()
 219  * @see streamrecorder_unset_error_cb()
 220  */
 221 typedef void (*streamrecorder_error_cb)(streamrecorder_error_e error, streamrecorder_state_e current_state, void *user_data);
 222
 223 /**
 224  * @brief Called iteratively to notify about the buffer has been consumed.
 225  * @since_tizen 3.0
 226  * @remarks The user needs to release consumed buffer if buffer is allocated by user including media packet
 227  * @param[in] buffer  The consumed buffer that user pushed
 228  * @param[in] user_data The user data passed
 229  * @see streamrecorder_set_buffer_consume_completed_cb() will invoke this callback.
 230  * @see streamrecorder_unset_buffer_consume_completed_cb()
 231  */
 232 typedef void (*streamrecorder_consume_completed_cb)(void *buffer, void *user_data);
 233
 234 /**
 235  * @}
 236  */
 237
 238 /**
 239  * @addtogroup CAPI_MEDIA_STREAMRECORDER_CAPABILITY_MODULE
 240  * @{
 241  */
 242
 243 /**
 244  * @brief Called once for each supported video resolution.
 245  * @since_tizen 3.0
 246  * @param[in] width         The video image width
 247  * @param[in] height        The video image height
 248  * @param[in] user_data     The user data passed from the foreach function
 249  * @return    @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop
 250  * @pre streamrecorder_foreach_supported_video_resolution() will invoke this callback.
 251  * @see streamrecorder_foreach_supported_video_resolution()
 252  */
 253 typedef bool (*streamrecorder_supported_video_resolution_cb)(int width, int height, void *user_data);
 254
 255 /**
 256  * @brief Called iteratively to notify about the supported file formats.
 257  * @since_tizen 3.0
 258  * @param[in] format   The format of recording files
 259  * @param[in] user_data The user data passed from the foreach function
 260  * @return @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop
 261  * @pre streamrecorder_foreach_supported_file_format() will invoke this callback.
 262  * @see streamrecorder_foreach_supported_file_format()
 263  */
 264 typedef bool (*streamrecorder_supported_file_format_cb)(streamrecorder_file_format_e format, void *user_data);
 265
 266 /**
 267  * @brief Called iteratively to notify about the supported audio encoders.
 268  * @since_tizen 3.0
 269  * @param[in] codec     The codec of audio encoder
 270  * @param[in] user_data The user data passed from the foreach function
 271  * @return @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop
 272  * @pre streamrecorder_foreach_supported_audio_encoder() will invoke this callback.
 273  * @see streamrecorder_foreach_supported_audio_encoder()
 274  */
 275 typedef bool (*streamrecorder_supported_audio_encoder_cb)(streamrecorder_audio_codec_e codec, void *user_data);
 276
 277 /**
 278  * @brief Called iteratively to notify about the supported video encoders.
 279  * @since_tizen 3.0
 280  * @param[in] codec     The codec of video encoder
 281  * @param[in] user_data The user data passed from the foreach function
 282  * @return @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop
 283  * @pre streamrecorder_foreach_supported_video_encoder() will invoke this callback.
 284  * @see streamrecorder_foreach_supported_video_encoder()
 285  */
 286 typedef bool (*streamrecorder_supported_video_encoder_cb)(streamrecorder_video_codec_e codec, void *user_data);
 287
 288 /**
 289  * @}
 290  */
 291
 292 /**
 293  * @addtogroup CAPI_MEDIA_STREAMRECORDER_MODULE
 294  * @{
 295  */
 296
 297 /**
 298  * @brief Creates a streamrecorder handle to record a video or audio.
 299  * @since_tizen 3.0
 300  * @remarks You must release @a recorder using streamrecorder_destroy().
 301  * @param[out]  recorder        A handle to the streamrecorder
 302  * @return @c 0 on success, otherwise a negative error value
 303  * @retval #STREAMRECORDER_ERROR_NONE Successful
 304  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 305  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #STREAMRECORDER_ERROR_OUT_OF_MEMORY Out of memory
 307  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 308  */
 309 int streamrecorder_create(streamrecorder_h *recorder);
 310
 311 /**
 312  * @brief Destroys the streamrecorder handle.
 313  * @since_tizen 3.0
 314  * @param[in]   recorder    The handle to the streamrecorder
 315  * @return @c 0 on success, otherwise a negative error value
 316  * @retval #STREAMRECORDER_ERROR_NONE Successful
 317  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 318  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 320  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 321  * @pre Create a stream recorder handle by calling streamrecorder_create().
 322  * @pre  The recorder state should be #STREAMRECORDER_STATE_CREATED.
 323  * @post The recorder state will be #STREAMRECORDER_STATE_NONE.
 324  * @see streamrecorder_create()
 325  */
 326 int streamrecorder_destroy(streamrecorder_h recorder);
 327
 328 /**
 329  * @brief Prepares the streamrecorder for recording.
 330  * @since_tizen 3.0
 331  * @remarks Before calling the function, it is required to properly set streamrecorder_enable_source_buffer(),
 332  *          audio encoder (streamrecorder_set_audio_encoder()),
 333  *          video encoder(streamrecorder_set_video_encoder()) and file format (streamrecorder_set_file_format()).
 334  * @param[in]   recorder  The handle to the streamrecorder
 335  * @return @c 0 on success, otherwise a negative error value
 336  * @retval #STREAMRECORDER_ERROR_NONE Successful
 337  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 338  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 339  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 340  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 341  * @pre Create a stream recorder handle by calling streamrecorder_create().
 342  * @pre  The recorder state should be #STREAMRECORDER_STATE_CREATED. \n
 343  *           The streamrecorder_enable_source_buffer() should be invoked before this function.
 344  * @post The streamrecorder state will be #STREAMRECORDER_STATE_PREPARED
 345  * @see streamrecorder_create()
 346  * @see streamrecorder_unprepare()
 347  * @see streamrecorder_set_audio_encoder()
 348  * @see streamrecorder_set_video_encoder()
 349  * @see streamrecorder_set_file_format()
 350  */
 351 int streamrecorder_prepare(streamrecorder_h recorder);
 352
 353 /**
 354  * @brief Resets the streamrecorder.
 355  * @since_tizen 3.0
 356  * @param[in]  recorder  The handle to the streamrecorder
 357  * @return @c 0 on success, otherwise a negative error value
 358  * @retval #STREAMRECORDER_ERROR_NONE Successful
 359  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 360  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 361  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 362  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 363  * @pre Create a stream recorder handle by calling streamrecorder_create().
 364  * @pre  The streamrecorder state should be #STREAMRECORDER_STATE_PREPARED set by streamrecorder_prepare(), streamrecorder_cancel() or streamrecorder_commit().
 365  * @post The streamrecorder state will be #STREAMRECORDER_STATE_CREATED.
 366  * @see streamrecorder_create()
 367  * @see streamrecorder_prepare()
 368  * @see streamrecorder_cancel()
 369  * @see streamrecorder_commit()
 370  */
 371 int streamrecorder_unprepare(streamrecorder_h recorder);
 372
 373 /**
 374  * @brief Starts the recording.
 375  * @since_tizen 3.0
 376  * @remarks If file path has been set to an existing file, this file is removed automatically and updated by new one. \n
 377  *          When you want to record audio or video file, you need to add privilege according to rules below additionally. \n
 378  *          %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 379  *          %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 380  *          The filename should be set before this function is invoked.
 381  * @param[in]  recorder  The handle to the streamrecorder
 382  * @return @c 0 on success, otherwise a negative error value
 383  * @retval #STREAMRECORDER_ERROR_NONE Successful
 384  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 385  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 386  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 387  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 388  * @retval #STREAMRECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted
 389  * @pre Create a stream recorder handle by calling streamrecorder_create().
 390  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_PREPARED by streamrecorder_prepare() or #STREAMRECORDER_STATE_PAUSED by streamrecorder_pause(). \n
 391  * The filename should be set by streamrecorder_set_filename().
 392  * @post The recorder state will be #STREAMRECORDER_STATE_RECORDING.
 393  * @see streamrecorder_create()
 394  * @see streamrecorder_pause()
 395  * @see streamrecorder_commit()
 396  * @see streamrecorder_cancel()
 397  * @see streamrecorder_set_audio_encoder()
 398  * @see streamrecorder_set_filename()
 399  * @see streamrecorder_set_file_format()
 400  * @see streamrecorder_recording_status_cb()
 401  * @see streamrecorder_set_filename()
 402  */
 403 int streamrecorder_start(streamrecorder_h recorder);
 404
 405 /**
 406  * @brief Pauses the recording.
 407  * @since_tizen 3.0
 408  * @remarks Recording can be resumed with streamrecorder_start().
 409  * @param[in]  recorder  The handle to the streamrecorder
 410  * @return @c 0 on success, otherwise a negative error value
 411  * @retval #STREAMRECORDER_ERROR_NONE Successful
 412  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 413  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 414  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 415  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 416  * @pre Create a stream recorder handle by calling streamrecorder_create().
 417  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_RECORDING.
 418  * @post The streamrecorder state will be #STREAMRECORDER_STATE_PAUSED.
 419  * @see streamrecorder_create()
 420  * @see streamrecorder_commit()
 421  * @see streamrecorder_cancel()
 422  */
 423 int streamrecorder_pause(streamrecorder_h recorder);
 424
 425 /**
 426  * @brief Stops recording and saves the result.
 427  * @since_tizen 3.0
 428  * @remarks When you want to record audio or video file, you need to add privilege according to rules below additionally. \n
 429  *          %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 430  *          %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 431  * @param[in]  recorder  The handle to the streamrecorder
 432  * @return @c 0 on success, otherwise a negative error value
 433  * @retval #STREAMRECORDER_ERROR_NONE Successful
 434  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 435  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 436  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 437  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 438  * @retval #STREAMRECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted
 439  * @pre Create a stream recorder handle by calling streamrecorder_create().
 440  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_RECORDING set by streamrecorder_start() or #STREAMRECORDER_STATE_PAUSED by streamrecorder_pause().
 441  * @post The streamrecorder state will be #STREAMRECORDER_STATE_PREPARED.
 442  * @see streamrecorder_create()
 443  * @see streamrecorder_pause()
 444  * @see streamrecorder_cancel()
 445  * @see streamrecorder_set_filename()
 446  * @see streamrecorder_start()
 447  */
 448 int streamrecorder_commit(streamrecorder_h recorder);
 449
 450 /**
 451  * @brief Cancels the recording.
 452  * @details The recording data is discarded and not written in the recording file.
 453  * @since_tizen 3.0
 454  * @remarks When you want to record audio or video file, you need to add privilege according to rules below additionally. \n
 455  *          %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 456  *          %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 457  * @param[in]  recorder  The handle to the streamrecorder
 458  * @return @c 0 on success, otherwise a negative error value
 459  * @retval #STREAMRECORDER_ERROR_NONE Successful
 460  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 461  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 462  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 463  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 464  * @retval #STREAMRECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted
 465  * @pre Create a stream recorder handle by calling streamrecorder_create().
 466  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_RECORDING set by streamrecorder_start() or #STREAMRECORDER_STATE_PAUSED by streamrecorder_pause().
 467  * @post The streamrecorder state will be #STREAMRECORDER_STATE_PREPARED.
 468  * @see streamrecorder_create()
 469  * @see streamrecorder_pause()
 470  * @see streamrecorder_commit()
 471  * @see streamrecorder_start()
 472  */
 473 int streamrecorder_cancel(streamrecorder_h recorder);
 474
 475 /**
 476  * @brief Pushes buffer to StreamRecorder to record audio/video.
 477  * @since_tizen 3.0
 478  * @remarks When you want to record audio or video file, you need to add privilege according to rules below additionally. \n
 479  *          %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
 480  *          %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 481  * @param[in]   recorder        The handle to the streamrecorder
 482  * @param[in]   inbuf The media packet containing buffer and other associated values
 483  * @return  @c 0 on success, otherwise a negative error value
 484  * @retval #STREAMRECORDER_ERROR_NONE Successful
 485  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 486  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 487  * @retval #STREAMRECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted
 488  * @pre Create a stream recorder handle by calling streamrecorder_create().
 489  * @see streamrecorder_create()
 490  */
 491 int streamrecorder_push_stream_buffer(streamrecorder_h recorder, media_packet_h inbuf);
 492
 493 /**
 494  * @brief Sets the video source as live buffer to be used for recording.
 495  * @since_tizen 3.0
 496  * @remarks if you want to enable video or audio or both recording, call before streamrecorder_prepare()
 497  * @param[in]  recorder  A handle to the streamrecorder
 498  * @param[in]  type The type of source input
 499  * @return @c 0 on success, otherwise a negative error value
 500  * @retval #STREAMRECORDER_ERROR_NONE Successful
 501  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 502  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 503  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 504  * @pre Create a stream recorder handle by calling streamrecorder_create().
 505  * @pre The streamrecorder state must be only #STREAMRECORDER_STATE_CREATED
 506  * @see streamrecorder_create()
 507  */
 508 int streamrecorder_enable_source_buffer(streamrecorder_h recorder, streamrecorder_source_e type);
 509
 510 /**
 511  * @brief Gets the streamrecorder's current state.
 512  * @since_tizen 3.0
 513  * @param[in]  recorder The handle to the streamrecorder
 514  * @param[out]  state  The current state of the streamrecorder
 515  * @return  @c 0 on success, otherwise a negative error value
 516  * @retval #STREAMRECORDER_ERROR_NONE Successful
 517  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 518  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 519  * @pre Create a stream recorder handle by calling streamrecorder_create().
 520  * @see streamrecorder_create()
 521  */
 522 int streamrecorder_get_state(streamrecorder_h recorder, streamrecorder_state_e *state);
 523
 524 /**
 525  * @}
 526  */
 527
 528 /**
 529  * @addtogroup CAPI_MEDIA_STREAMRECORDER_ATTRIBUTES_MODULE
 530  * @{
 531  */
 532
 533
 534 /**
 535  * @brief Sets the file path to record.
 536  * @details This function sets file path which defines where newly recorded data should be stored.
 537  * @since_tizen 3.0
 538  * @remarks If the same file already exists in the file system, then old file will be overwritten.
 539  * @param[in]   recorder        The handle to the streamrecorder
 540  * @param[in]   path The recording file path
 541  * @return @c 0 on success, otherwise a negative error value
 542  * @retval #STREAMRECORDER_ERROR_NONE Successful
 543  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 544  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 545  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 546  * @pre Create a stream recorder handle by calling streamrecorder_create().
 547  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 548  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 549  * @see streamrecorder_create()
 550  * @see streamrecorder_get_filename()
 551  */
 552 int streamrecorder_set_filename(streamrecorder_h recorder, const char *path);
 553
 554 /**
 555  * @brief Gets the file path to record.
 556  * @since_tizen 3.0
 557  * @remarks You must release @a path using free().
 558  * @param[in]   recorder    The handle to the streamrecorder
 559  * @param[out]  path    The recording file path
 560  * @return @c 0 on success, otherwise a negative error value
 561  * @retval #STREAMRECORDER_ERROR_NONE Successful
 562  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 563  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 564  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 565  * @pre Create a stream recorder handle by calling streamrecorder_create().
 566  * @see streamrecorder_create()
 567  * @see streamrecorder_set_filename()
 568  */
 569 int streamrecorder_get_filename(streamrecorder_h recorder, char **path);
 570
 571 /**
 572  * @brief Sets the file format for recording media stream.
 573  * @since_tizen 3.0
 574  * @param[in] recorder The handle to the streamrecorder
 575  * @param[in] format   The media file format
 576  * @return @c 0 on success, otherwise a negative error value
 577  * @retval #STREAMRECORDER_ERROR_NONE Successful
 578  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 579  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 580  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 581  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 582  * @pre Create a stream recorder handle by calling streamrecorder_create().
 583  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 584  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 585  * @see streamrecorder_create()
 586  * @see streamrecorder_get_file_format()
 587  * @see streamrecorder_foreach_supported_file_format()
 588  */
 589 int streamrecorder_set_file_format(streamrecorder_h recorder, streamrecorder_file_format_e format);
 590
 591
 592 /**
 593  * @brief Gets the file format for recording media stream.
 594  * @since_tizen 3.0
 595  * @param[in] recorder The handle to the streamrecorder
 596  * @param[out] format   The media file format
 597  * @return @c 0 on success, otherwise a negative error value
 598  * @retval #STREAMRECORDER_ERROR_NONE Successful
 599  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 600  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 601  * @pre Create a stream recorder handle by calling streamrecorder_create().
 602  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 603  * @see streamrecorder_create()
 604  * @see streamrecorder_set_file_format()
 605  * @see streamrecorder_foreach_supported_file_format()
 606  */
 607 int streamrecorder_get_file_format(streamrecorder_h recorder, streamrecorder_file_format_e *format);
 608
 609 /**
 610  * @brief Sets the audio codec for encoding an audio stream.
 611  * @since_tizen 3.0
 612  * @remarks You can get available audio encoders by using streamrecorder_foreach_supported_audio_encoder(). \n
 613  * @param[in] recorder The handle to the streamrecorder
 614  * @param[in] codec    The audio codec
 615  * @return @c 0 on success, otherwise a negative error value
 616  * @retval #STREAMRECORDER_ERROR_NONE Successful
 617  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 618  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 619  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 620  * @retval #STREAMRECORDER_ERROR_INVALID_OPERATION Invalid operation
 621  * @pre Create a stream recorder handle by calling streamrecorder_create().
 622  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 623  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 624  * @see streamrecorder_create()
 625  * @see streamrecorder_get_audio_encoder()
 626  * @see streamrecorder_foreach_supported_audio_encoder()
 627  */
 628 int streamrecorder_set_audio_encoder(streamrecorder_h recorder, streamrecorder_audio_codec_e codec);
 629
 630 /**
 631  * @brief Gets the audio codec for encoding an audio stream.
 632  * @since_tizen 3.0
 633  * @param[in] recorder The handle to the streamrecorder
 634  * @param[out] codec   The audio codec
 635  * @return @c 0 on success, otherwise a negative error value
 636  * @retval #STREAMRECORDER_ERROR_NONE Successful
 637  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 638  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 639  * @pre Create a stream recorder handle by calling streamrecorder_create().
 640  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 641  * @see streamrecorder_create()
 642  * @see streamrecorder_set_audio_encoder()
 643  * @see streamrecorder_foreach_supported_audio_encoder()
 644  */
 645 int streamrecorder_get_audio_encoder(streamrecorder_h recorder, streamrecorder_audio_codec_e *codec);
 646
 647 /**
 648  * @brief Sets the resolution of the video recording.
 649  * @since_tizen 3.0
 650  * @remarks This function should be called before recording (streamrecorder_start()).
 651  * @param[in] recorder  The handle to the streamrecorder
 652  * @param[in] width     The input width
 653  * @param[in] height    The input height
 654  * @return @c 0 on success, otherwise a negative error value
 655  * @retval #STREAMRECORDER_ERROR_NONE Successful
 656  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 657  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 658  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 659  * @pre Create a stream recorder handle by calling streamrecorder_create().
 660  * @pre    The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 661  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 662  * @see streamrecorder_create()
 663  * @see streamrecorder_start()
 664  * @see streamrecorder_get_video_resolution()
 665  * @see streamrecorder_foreach_supported_video_resolution()
 666  */
 667 int streamrecorder_set_video_resolution(streamrecorder_h recorder, int width, int height);
 668
 669 /**
 670  * @brief Gets the resolution of the video recording.
 671  * @since_tizen 3.0
 672  * @param[in] recorder  The handle to the streamrecorder
 673  * @param[out] width    The video width
 674  * @param[out] height   The video height
 675  * @return @c 0 on success, otherwise a negative error value
 676  * @retval #STREAMRECORDER_ERROR_NONE Successful
 677  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 678  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 679  * @pre Create a stream recorder handle by calling streamrecorder_create().
 680  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 681  * @see streamrecorder_create()
 682  * @see streamrecorder_set_video_resolution()
 683  * @see streamrecorder_foreach_supported_video_resolution()
 684  */
 685 int streamrecorder_get_video_resolution(streamrecorder_h recorder, int *width, int *height);
 686
 687 /**
 688  * @brief Sets the video codec for encoding video stream.
 689  * @since_tizen 3.0
 690  * @remarks You can get available video encoders by using recorder_foreach_supported_video_encoder().
 691  * @param[in] recorder The handle to the streamrecorder
 692  * @param[in] codec    The video codec
 693  * @return @c 0 on success, otherwise a negative error value
 694  * @retval #STREAMRECORDER_ERROR_NONE Successful
 695  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 696  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 697  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 698  * @pre Create a stream recorder handle by calling streamrecorder_create().
 699  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 700  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 701  * @see streamrecorder_create()
 702  * @see streamrecorder_get_video_encoder()
 703  * @see streamrecorder_foreach_supported_video_encoder()
 704  */
 705 int streamrecorder_set_video_encoder(streamrecorder_h recorder, streamrecorder_video_codec_e codec);
 706
 707 /**
 708  * @brief Gets the video codec for encoding video stream.
 709  * @since_tizen 3.0
 710  * @param[in] recorder The handle to the streamrecorder
 711  * @param[out] codec   The video codec
 712  * @return @c 0 on success, otherwise a negative error value
 713  * @retval #STREAMRECORDER_ERROR_NONE Successful
 714  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 715  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 716  * @pre Create a stream recorder handle by calling streamrecorder_create().
 717  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 718  * @see streamrecorder_create()
 719  * @see streamrecorder_set_video_encoder()
 720  * @see streamrecorder_foreach_supported_video_encoder()
 721  */
 722 int streamrecorder_get_video_encoder(streamrecorder_h recorder, streamrecorder_video_codec_e *codec);
 723
 724 /**
 725  * @brief Sets the recording frame rate.
 726  * @since_tizen 3.0
 727  * @remarks This function should be called before prepared state.
 728  * @param[in] recorder The handle to the streamrecorder
 729  * @param[in] framerate The frame rate for recording
 730  * @return @c 0 on success, otherwise a negative error value
 731  * @retval #STREAMRECORDER_ERROR_NONE Successful
 732  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 733  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 734  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 735  * @pre Create a stream recorder handle by calling streamrecorder_create().
 736  * @see streamrecorder_create()
 737  * @see streamrecorder_get_video_framerate()
 738  */
 739 int streamrecorder_set_video_framerate(streamrecorder_h recorder, int framerate);
 740
 741 /**
 742  * @brief Gets the recording frame rate.
 743  * @since_tizen 3.0
 744  * @param[in] recorder The handle to the camera
 745  * @param[out] framerate The frame rate for recording that already is set
 746  * @return @c 0 on success, otherwise a negative error value
 747  * @retval #STREAMRECORDER_ERROR_NONE Successful
 748  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 749  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 750  * @pre Create a stream recorder handle by calling streamrecorder_create().
 751  * @see streamrecorder_create()
 752  * @see streamrecorder_set_video_framerate()
 753  */
 754 int streamrecorder_get_video_framerate(streamrecorder_h recorder, int *framerate);
 755
 756 /**
 757  * @brief Sets the video source format.
 758  * @since_tizen 3.0
 759  * @remarks This function should be called before prepared state.
 760  * @param[in] recorder The handle to the streamrecorder
 761  * @param[in] format The color type of video source
 762  * @return @c 0 on success, otherwise a negative error value
 763  * @retval #STREAMRECORDER_ERROR_NONE Successful
 764  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 765  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 766  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 767  * @pre Create a stream recorder handle by calling streamrecorder_create().
 768  * @see streamrecorder_create()
 769  * @see streamrecorder_get_video_source_format()
 770  */
 771 int streamrecorder_set_video_source_format(streamrecorder_h recorder, streamrecorder_video_source_format_e format);
 772
 773 /**
 774  * @brief Gets the video source format.
 775  * @since_tizen 3.0
 776  * @remarks This function should be called before prepared state.
 777  * @param[in] recorder The handle to the streamrecorder
 778  * @param[out] format The color type of video source that already is set
 779  * @return @c 0 on success, otherwise a negative error value
 780  * @retval #STREAMRECORDER_ERROR_NONE Successful
 781  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 782  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 783  * @pre Create a stream recorder handle by calling streamrecorder_create().
 784  * @see streamrecorder_create()
 785  * @see streamrecorder_set_video_source_format()
 786  */
 787 int streamrecorder_get_video_source_format(streamrecorder_h recorder, streamrecorder_video_source_format_e *format);
 788
 789 /**
 790  * @brief Sets the maximum size of a recording file.
 791  * @since_tizen 3.0
 792  * @remarks After reaching the limitation, the recording data is discarded and not written in the recording file.
 793  * @param[in] recorder The handle to the streamrecorder
 794  * @param[in] type The recording limit type
 795  * @param[in] limit If limit type is #STREAMRECORDER_RECORDING_LIMIT_TYPE_SIZE, the limit value is the maximum size of the recording file(KB), \n
 796  *                            otherwise limit value is the maximum time of the recording file (in seconds) \n
 797  *                     @c 0 means unlimited recording size or time.
 798  * @return @c 0 on success, otherwise a negative error value
 799  * @retval #STREAMRECORDER_ERROR_NONE Successful
 800  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 801  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 802  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 803  * @pre Create a stream recorder handle by calling streamrecorder_create().
 804  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 805  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 806  * @see streamrecorder_create()
 807  * @see streamrecorder_get_recording_limit()
 808  */
 809 int streamrecorder_set_recording_limit(streamrecorder_h recorder, streamrecorder_recording_limit_type_e type, int limit);
 810
 811 /**
 812  * @brief Gets the maximum size of a recording file.
 813  * @since_tizen 3.0
 814  * @param[in] recorder The handle to the streamrecorder
 815  * @param[in] type The recording limit type
 816  * @param[out] limit If limit type is #STREAMRECORDER_RECORDING_LIMIT_TYPE_SIZE, the limit value is the maximum size of the recording file(KB), \n
 817  *                            otherwise limit value is the maximum time of the recording file (in seconds) \n
 818  *                     @c 0 means unlimited recording size or time.
 819  * @return @c 0 on success, otherwise a negative error value
 820  * @retval #STREAMRECORDER_ERROR_NONE Successful
 821  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 822  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 823  * @pre Create a stream recorder handle by calling streamrecorder_create().
 824  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 825  * @see streamrecorder_create()
 826  * @see streamrecorder_set_recording_limit()
 827  */
 828 int streamrecorder_get_recording_limit(streamrecorder_h recorder, streamrecorder_recording_limit_type_e type, int *limit);
 829
 830 /**
 831  * @brief Sets the sampling rate of an audio stream.
 832  * @since_tizen 3.0
 833  * @param[in] recorder    The handle to the streamrecorder
 834  * @param[in] samplerate The sample rate in Hertz
 835  * @return @c 0 on success, otherwise a negative error value
 836  * @retval #STREAMRECORDER_ERROR_NONE Successful
 837  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 838  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 839  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 840  * @pre Create a stream recorder handle by calling streamrecorder_create().
 841  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 842  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 843  * @see streamrecorder_create()
 844  * @see streamrecorder_get_audio_samplerate()
 845  */
 846 int streamrecorder_set_audio_samplerate(streamrecorder_h recorder, int samplerate);
 847
 848 /**
 849  * @brief Gets the sampling rate of an audio stream.
 850  * @since_tizen 3.0
 851  * @param[in]  recorder    The handle to the streamrecorder
 852  * @param[out] samplerate  The sample rate in Hertz
 853  * @return @c 0 on success, otherwise a negative error value
 854  * @retval #STREAMRECORDER_ERROR_NONE Successful
 855  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 856  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 857  * @pre Create a stream recorder handle by calling streamrecorder_create().
 858  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 859  * @see streamrecorder_create()
 860  * @see streamrecorder_set_audio_samplerate()
 861  */
 862 int streamrecorder_get_audio_samplerate(streamrecorder_h recorder, int *samplerate);
 863
 864 /**
 865  * @brief Sets the bitrate of an audio encoder.
 866  * @since_tizen 3.0
 867  * @param[in] recorder  The handle to the streamrecorder
 868  * @param[in] bitrate   The bitrate (for mms : 12200[bps], normal : 288000[bps])
 869  * @return @c 0 on success, otherwise a negative error value
 870  * @retval #STREAMRECORDER_ERROR_NONE Successful
 871  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 872  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 873  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 874  * @pre Create a stream recorder handle by calling streamrecorder_create().
 875  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 876  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 877  * @see streamrecorder_create()
 878  * @see streamrecorder_get_audio_encoder_bitrate()
 879  */
 880 int streamrecorder_set_audio_encoder_bitrate(streamrecorder_h recorder, int bitrate);
 881
 882 /**
 883  * @brief Sets the bitrate of a video encoder.
 884  * @since_tizen 3.0
 885  * @param[in] recorder  The handle to the streamrecorder
 886  * @param[in] bitrate   The bitrate in bits per second
 887  * @return @c 0 on success, otherwise a negative error value
 888  * @retval #STREAMRECORDER_ERROR_NONE Successful
 889  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 890  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 891  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 892  * @pre Create a stream recorder handle by calling streamrecorder_create().
 893  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED. \n
 894  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 895  * @see streamrecorder_create()
 896  * @see streamrecorder_get_video_encoder_bitrate()
 897  */
 898 int streamrecorder_set_video_encoder_bitrate(streamrecorder_h recorder, int bitrate);
 899
 900 /**
 901  * @brief Gets the bitrate of an audio encoder.
 902  * @since_tizen 3.0
 903  * @param[in]  recorder  The handle to the streamrecorder
 904  * @param[out] bitrate   The bitrate in bits per second
 905  * @return @c 0 on success, otherwise a negative error value
 906  * @retval #STREAMRECORDER_ERROR_NONE Successful
 907  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 908  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 909  * @pre Create a stream recorder handle by calling streamrecorder_create().
 910  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 911  * @see streamrecorder_create()
 912  * @see streamrecorder_set_audio_encoder_bitrate()
 913  */
 914 int streamrecorder_get_audio_encoder_bitrate(streamrecorder_h recorder, int *bitrate);
 915
 916 /**
 917  * @brief Gets the bitrate of a video encoder.
 918  * @since_tizen 3.0
 919  * @param[in]  recorder  The handle to the streamrecorder
 920  * @param[out] bitrate   The bitrate in bits per second
 921  * @return @c 0 on success, otherwise a negative error value
 922  * @retval #STREAMRECORDER_ERROR_NONE Successful
 923  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 924  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 925  * @pre Create a stream recorder handle by calling streamrecorder_create().
 926  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 927  * @see streamrecorder_create()
 928  * @see streamrecorder_set_audio_encoder_bitrate()
 929  */
 930 int streamrecorder_get_video_encoder_bitrate(streamrecorder_h recorder, int *bitrate);
 931
 932 /**
 933  * @brief Sets the number of the audio channel.
 934  * @since_tizen 3.0
 935  * @remarks This attribute is applied only in #STREAMRECORDER_STATE_CREATED state. \n
 936  *          For mono recording, setting channel to @c 1. \n
 937  *          For stereo recording, setting channel to @c 2.
 938  * @param[in] recorder       The handle to the streamrecorder
 939  * @param[in] channel_count  The number of the audio channel
 940  * @return @c 0 on success, otherwise a negative error value
 941  * @retval #STREAMRECORDER_ERROR_NONE Successful
 942  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 943  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 944  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 945  * @pre Create a stream recorder handle by calling streamrecorder_create().
 946  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED.\n
 947  *          streamrecorder_enable_source_buffer() should be invoked before this function.
 948  * @see streamrecorder_create()
 949  * @see streamrecorder_get_audio_channel()
 950  */
 951 int streamrecorder_set_audio_channel(streamrecorder_h recorder, int channel_count);
 952
 953 /**
 954  * @brief Gets the number of the audio channel.
 955  * @since_tizen 3.0
 956  * @param[in] recorder  The handle to the streamrecorder
 957  * @param[out] channel_count  The number of the audio channel
 958  * @return @c 0 on success, otherwise a negative error value
 959  * @retval #STREAMRECORDER_ERROR_NONE Successful
 960  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 961  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 962  * @pre Create a stream recorder handle by calling streamrecorder_create().
 963  * @pre The streamrecorder_enable_source_buffer() should be invoked before this function.
 964  * @see streamrecorder_create()
 965  * @see streamrecorder_set_audio_channel()
 966  */
 967 int streamrecorder_get_audio_channel(streamrecorder_h recorder, int *channel_count);
 968
 969 /**
 970  * @brief Sets the recording mode.
 971  * @since_tizen 6.0
 972  * @remarks This attribute can be set only in the #STREAMRECORDER_STATE_CREATED state. \n
 973  *          To record with media buffer, set the mode to #STREAMRECORDER_MODE_STREAM_BUFFER. \n
 974  *          To record with the device's own screen (display) and audio, set the mode to #STREAMRECORDER_MODE_DEVICE_LOOPBACK.
 975  * @param[in] recorder       The handle to the streamrecorder
 976  * @param[in] mode  The recording mode
 977  * @return @c 0 on success, otherwise a negative error value
 978  * @retval #STREAMRECORDER_ERROR_NONE Successful
 979  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 980  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 981  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
 982  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED.\n
 983  * @see streamrecorder_create()
 984  * @see streamrecorder_get_mode()
 985  */
 986 int streamrecorder_set_mode(streamrecorder_h recorder, streamrecorder_mode_e mode);
 987
 988 /**
 989  * @brief Gets the recording mode.
 990  * @since_tizen 6.0
 991  * @remarks #STREAMRECORDER_MODE_STREAM_BUFFER indicates recording with media buffer. \n
 992  *          #STREAMRECORDER_MODE_DEVICE_LOOPBACK indicates recording the device's own screen (display) and audio.
 993  * @param[in] recorder       The handle to the streamrecorder
 994  * @param[out] mode  The recording mode
 995  * @return @c 0 on success, otherwise a negative error value
 996  * @retval #STREAMRECORDER_ERROR_NONE Successful
 997  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
 998  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
 999  * @retval #STREAMRECORDER_ERROR_INVALID_STATE Invalid state
1000  * @pre The streamrecorder state must be #STREAMRECORDER_STATE_CREATED.\n
1001  * @see streamrecorder_create()
1002  * @see streamrecorder_set_mode()
1003  */
1004 int streamrecorder_get_mode(streamrecorder_h recorder, streamrecorder_mode_e *mode);
1005
1006 /**
1007  * @}
1008  */
1009
1010 /**
1011  * @addtogroup CAPI_MEDIA_STREAMRECORDER_CAPABILITY_MODULE
1012  * @{
1013  */
1014
1015
1016 /**
1017  * @brief Retrieves all supported file formats by invoking a specific callback for each supported file format.
1018  * @since_tizen 3.0
1019  * @param[in] recorder  The handle to the streamrecorder
1020  * @param[in] callback The iteration callback
1021  * @param[in] user_data The user data to be passed to the callback function
1022  * @return @c 0 on success, otherwise a negative error value
1023  * @retval #STREAMRECORDER_ERROR_NONE Successful
1024  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1025  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1026  * @pre Create a stream recorder handle by calling streamrecorder_create().
1027  * @post  streamrecorder_supported_file_format_cb() will be invoked.
1028  * @see streamrecorder_create()
1029  * @see streamrecorder_get_file_format()
1030  * @see streamrecorder_set_file_format()
1031  * @see streamrecorder_supported_file_format_cb()
1032  */
1033 int streamrecorder_foreach_supported_file_format(streamrecorder_h recorder, streamrecorder_supported_file_format_cb callback, void *user_data);
1034
1035 /**
1036  * @brief Retrieves all supported audio encoders by invoking a specific callback for each supported audio encoder.
1037  * @since_tizen 3.0
1038  * @param[in] recorder  The handle to the streamrecorder
1039  * @param[in] callback  The iteration callback
1040  * @param[in] user_data The user data to be passed to the callback function
1041  * @return @c 0 on success, otherwise a negative error value
1042  * @retval #STREAMRECORDER_ERROR_NONE Successful
1043  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1044  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1045  * @pre Create a stream recorder handle by calling streamrecorder_create().
1046  * @post  streamrecorder_supported_audio_encoder_cb() will be invoked.
1047  * @see streamrecorder_create()
1048  * @see streamrecorder_set_audio_encoder()
1049  * @see streamrecorder_get_audio_encoder()
1050  * @see streamrecorder_supported_audio_encoder_cb()
1051  */
1052 int streamrecorder_foreach_supported_audio_encoder(streamrecorder_h recorder, streamrecorder_supported_audio_encoder_cb callback, void *user_data);
1053
1054 /**
1055  * @brief Retrieves all supported video encoders by invoking a specific callback for each supported video encoder.
1056  * @since_tizen 3.0
1057  * @param[in] recorder  The handle to the streamrecorder
1058  * @param[in] callback  The iteration callback
1059  * @param[in] user_data The user data to be passed to the callback function
1060  * @return @c 0 on success, otherwise a negative error value
1061  * @retval #STREAMRECORDER_ERROR_NONE Successful
1062  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1063  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1064  * @pre Create a stream recorder handle by calling streamrecorder_create().
1065  * @post  streamrecorder_supported_video_encoder_cb() will be invoked.
1066  * @see streamrecorder_create()
1067  * @see streamrecorder_set_video_encoder()
1068  * @see streamrecorder_get_video_encoder()
1069  * @see streamrecorder_supported_video_encoder_cb()
1070  */
1071 int streamrecorder_foreach_supported_video_encoder(streamrecorder_h recorder, streamrecorder_supported_video_encoder_cb callback, void *user_data);
1072
1073 /**
1074  * @brief Retrieves all supported video resolutions by invoking callback function once for each supported video resolution.
1075  * @since_tizen 3.0
1076  * @param[in] recorder  The handle to the streamrecorder
1077  * @param[in] foreach_cb        The callback function to be invoked
1078  * @param[in] user_data The user data to be passed to the callback function
1079  * @return @c 0 on success, otherwise a negative error value
1080  * @retval #STREAMRECORDER_ERROR_NONE Successful
1081  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1082  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1083  * @pre Create a stream recorder handle by calling streamrecorder_create().
1084  * @post        This function invokes streamrecorder_supported_video_resolution_cb() repeatedly to retrieve each supported video resolution.
1085  * @see streamrecorder_create()
1086  * @see streamrecorder_set_video_resolution()
1087  * @see streamrecorder_get_video_resolution()
1088  * @see streamrecorder_supported_video_resolution_cb()
1089  */
1090 int streamrecorder_foreach_supported_video_resolution(streamrecorder_h recorder,
1091                                                 streamrecorder_supported_video_resolution_cb foreach_cb, void *user_data);
1092
1093 /**
1094  * @}
1095  */
1096
1097 /**
1098  * @addtogroup CAPI_MEDIA_STREAMRECORDER_CALLBACK_MODULE
1099  * @{
1100  */
1101
1102
1103 /**
1104  * @brief Registers the callback function that will be invoked when the streamrecorder get some notification.
1105  * @since_tizen 3.0
1106  * @param[in] recorder  The handle to the streamrecorder
1107  * @param[in] callback  The function pointer of user callback
1108  * @param[in] user_data The user data to be passed to the callback function
1109  * @return @c 0 on success, otherwise a negative error value
1110  * @retval #STREAMRECORDER_ERROR_NONE Successful
1111  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1112  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1113  * @pre Create a stream recorder handle by calling streamrecorder_create().
1114  * @post  streamrecorder_notify_cb() will be invoked.
1115  * @see streamrecorder_create()
1116  * @see streamrecorder_unset_notify_cb()
1117  * @see streamrecorder_notify_cb()
1118  */
1119 int streamrecorder_set_notify_cb(streamrecorder_h recorder, streamrecorder_notify_cb callback, void *user_data);
1120
1121 /**
1122  * @brief Unregisters the callback function.
1123  * @since_tizen 3.0
1124  * @param[in]  recorder The handle to the streamrecorder
1125  * @return @c 0 on success, otherwise a negative error value
1126  * @retval #STREAMRECORDER_ERROR_NONE Successful
1127  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1128  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1129  * @pre Create a stream recorder handle by calling streamrecorder_create().
1130  * @see streamrecorder_create()
1131  * @see streamrecorder_set_notify_cb()
1132  */
1133 int streamrecorder_unset_notify_cb(streamrecorder_h recorder);
1134
1135 /**
1136  * @brief Registers a callback function to be invoked when the recording information changes.
1137  * @since_tizen 3.0
1138  * @param[in]  recorder   The handle to the streamrecorder
1139  * @param[in]  callback   The function pointer of user callback
1140  * @param[in]  user_data  The user data to be passed to the callback function
1141  * @return @c 0 on success, otherwise a negative error value
1142  * @retval #STREAMRECORDER_ERROR_NONE Successful
1143  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1144  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1145  * @pre Create a stream recorder handle by calling streamrecorder_create().
1146  * @post  streamrecorder_recording_status_cb() will be invoked.
1147  * @see streamrecorder_create()
1148  * @see streamrecorder_unset_recording_status_cb()
1149  * @see streamrecorder_recording_status_cb()
1150  */
1151 int streamrecorder_set_recording_status_cb(streamrecorder_h recorder, streamrecorder_recording_status_cb callback, void *user_data);
1152
1153 /**
1154  * @brief Unregisters the callback function.
1155  * @since_tizen 3.0
1156  * @param[in]  recorder    The handle to the streamrecorder
1157  * @return @c 0 on success, otherwise a negative error value
1158  * @retval #STREAMRECORDER_ERROR_NONE Successful
1159  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1160  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1161  * @pre Create a stream recorder handle by calling streamrecorder_create().
1162  * @see streamrecorder_set_recording_status_cb()
1163  */
1164 int streamrecorder_unset_recording_status_cb(streamrecorder_h recorder);
1165
1166 /**
1167  * @brief Registers the callback function to be run when reached the recording limit.
1168  * @since_tizen 3.0
1169  * @param[in]   recorder        The handle to streamrecorder
1170  * @param[in]   callback        The function pointer of user callback
1171  * @param[in]   user_data       The user data to be passed to the callback function
1172  * @return @c 0 on success, otherwise a negative error value
1173  * @retval #STREAMRECORDER_ERROR_NONE Successful
1174  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1175  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1176  * @pre Create a stream recorder handle by calling streamrecorder_create().
1177  * @post  streamrecorder_recording_limit_reached_cb() will be invoked.
1178  * @see streamrecorder_create()
1179  * @see streamrecorder_unset_recording_limit_reached_cb()
1180  * @see streamrecorder_set_time_limit()
1181  * @see streamrecorder_recording_limit_reached_cb()
1182  */
1183 int streamrecorder_set_recording_limit_reached_cb(streamrecorder_h recorder, streamrecorder_recording_limit_reached_cb callback, void *user_data);
1184
1185 /**
1186  * @brief Unregisters the callback function.
1187  * @since_tizen 3.0
1188  * @param[in]  recorder  The handle to the streamrecorder
1189  * @return @c 0 on success, otherwise a negative error value
1190  * @retval #STREAMRECORDER_ERROR_NONE Successful
1191  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1192  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1193  * @pre Create a stream recorder handle by calling streamrecorder_create().
1194  * @see streamrecorder_create()
1195  * @see streamrecorder_set_recording_limit_reached_cb()
1196  */
1197 int streamrecorder_unset_recording_limit_reached_cb(streamrecorder_h recorder);
1198
1199 /**
1200  * @brief Registers a callback function to be called when an asynchronous operation error occurred.
1201  * @since_tizen 3.0
1202  * @remarks This callback informs critical error situation.\n
1203  *          When this callback is invoked, user should release the resource and terminate the application. \n
1204  *          These error codes will occur. \n
1205  *          #STREAMRECORDER_ERROR_INVALID_OPERATION \n
1206  *          #STREAMRECORDER_ERROR_OUT_OF_MEMORY
1207  * @param[in]   recorder        The handle to the streamrecorder
1208  * @param[in]   callback        The callback function to register
1209  * @param[in]   user_data       The user data to be passed to the callback function
1210  * @return  @c 0 on success, otherwise a negative error value
1211  * @retval #STREAMRECORDER_ERROR_NONE Successful
1212  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1213  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1214  * @pre Create a stream recorder handle by calling streamrecorder_create().
1215  * @post        This function will invoke streamrecorder_error_cb() when an asynchronous operation error occur.
1216  * @see streamrecorder_create()
1217  * @see streamrecorder_unset_error_cb()
1218  * @see streamrecorder_error_cb()
1219  */
1220 int streamrecorder_set_error_cb(streamrecorder_h recorder, streamrecorder_error_cb callback, void *user_data);
1221
1222
1223 /**
1224  * @brief Unregisters the callback function.
1225  * @since_tizen 3.0
1226  * @param[in]   recorder        The handle to the streamrecorder
1227  * @return  @c on success, otherwise a negative error value
1228  * @retval    #STREAMRECORDER_ERROR_NONE Successful
1229  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1230  * @retval    #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1231  * @pre Create a stream recorder handle by calling streamrecorder_create().
1232  * @see streamrecorder_create()
1233  * @see streamrecorder_set_error_cb()
1234  */
1235 int streamrecorder_unset_error_cb(streamrecorder_h recorder);
1236
1237 /**
1238  * @brief Registers a callback function to be called when asynchronous buffers are consumed.
1239  * @since_tizen 3.0
1240  * @remarks This callback informs to user dealloc buffer.\n
1241  *          When this callback is invoked, user should release the buffer or media packet. \n
1242  * @param[in]   recorder        The handle to the streamrecorder
1243  * @param[in]   callback        The callback function to register
1244  * @param[in]   user_data       The user data to be passed to the callback function
1245  * @return  @c 0 on success, otherwise a negative error value
1246  * @retval #STREAMRECORDER_ERROR_NONE Successful
1247  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1248  * @retval #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1249  * @pre Create a stream recorder handle by calling streamrecorder_create().
1250  * @see streamrecorder_create()
1251  * @see streamrecorder_unset_buffer_consume_completed_cb()
1252  * @see streamrecorder_push_stream_buffer()
1253  */
1254 int streamrecorder_set_buffer_consume_completed_cb(streamrecorder_h recorder, streamrecorder_consume_completed_cb callback, void *user_data);
1255
1256 /**
1257  * @brief Unregisters the callback function.
1258  * @since_tizen 3.0
1259  * @param[in]   recorder        The handle to the streamrecorder
1260  * @return  @c on success, otherwise a negative error value
1261  * @retval    #STREAMRECORDER_ERROR_NONE Successful
1262  * @retval #STREAMRECORDER_ERROR_NOT_SUPPORTED Not supported
1263  * @retval    #STREAMRECORDER_ERROR_INVALID_PARAMETER Invalid parameter
1264  * @pre Create a stream recorder handle by calling streamrecorder_create().
1265  * @see streamrecorder_create()
1266  * @see streamrecorder_set_buffer_consume_completed_cb()
1267  */
1268 int streamrecorder_unset_buffer_consume_completed_cb(streamrecorder_h recorder);
1269
1270 /**
1271  * @}
1272  */
1273
1274 #ifdef __cplusplus
1275 }
1276 #endif
1277
1278 #endif /* __TIZEN_MEDIA_STREAMRECORDER_H__ */
1279