doc/streamrecorder_doc.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_STREAMRECORDER_DOC_H__
  19 #define __TIZEN_MEDIA_STREAMRECORDER_DOC_H__
  20
  21
  22 /**
  23  * @file streamrecorder_doc.h
  24  * @brief The file contains the high level documentation for the StreamRecorder API.
  25  */
  26
  27 /**
  28  * @ingroup CAPI_MEDIA_FRAMEWORK
  29  * @defgroup CAPI_MEDIA_STREAMRECORDER_MODULE StreamRecorder
  30  * @brief The @ref CAPI_MEDIA_STREAMRECORDER_MODULE API provides functions for StreamRecorder with buffer including media packet.
  31  *
  32  * @section CAPI_MEDIA_STREAMRECORDER_MODULE_HEADER Required Header
  33  *   \#include <streamrecorder.h>
  34  *
  35  * @section CAPI_MEDIA_STREAMRECORDER_MODULE_OVERVIEW Overview
  36  * The StreamRecorder API allows application developers to support using the video or audio recorder. It includes functions that record video or audio and supports to set up
  37  * notifications for state changes of creation, prepared, record, pause, information about resolution and binary data format, and functions for artistic.
  38  *
  39  * The StreamRecorder API allows creation of components required in recording video or audio including:
  40  * - selecting a proper output format
  41  * - controlling the StreamRecorder state
  42  * - getting supported formats and video resolutions
  43  *
  44  * The StreamRecorder API also notifies you (by callback mechanism) when a significant parameter changes.
  45  *
  46  * @subsection CAPI_MEDIA_STREAMRECORDER_DIFFERENCE Difference
  47  * Basically, the StreamRecorder API can help easily to make video/audio content same as the Recorder API.\n
  48  *
  49  * However, the StreamRecorder API is different from Recorder API. \n
  50  * The StreamRecorder API is able to record user buffer from application. This allows the user to make unique contents with a purpose.
  51  *
  52  * <div><table class="doxtable" >
  53  * <tr>
  54  *    <th><b>Difference </b></th>
  55  *    <th><b>Recorder</b></th>
  56  *    <th><b>StreamRecorder</b></th>
  57  * </tr>
  58  * <tr>
  59  *    <td> INPUT </td>
  60  *    <td> Camera / Mic Device </td>
  61  *    <td> Media Packet / Buffer </td>
  62  * </tr>
  63  * </table></div>
  64  *
  65  * @subsection CAPI_MEDIA_STREAMRECORDER_LIFE_CYCLE_STATE_DIAGRAM State Diagram
  66  * @image html capi_media_streamrecorder_state_diagram.png
  67  *
  68  * @subsection CAPI_MEDIA_STREAMRECORDER_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
  69  * <div><table class="doxtable" >
  70  * <tr>
  71  *    <th><b>FUNCTION</b></th>
  72  *    <th><b>PRE-STATE</b></th>
  73  *    <th><b>POST-STATE</b></th>
  74  *    <th><b>SYNC TYPE</b></th>
  75  * </tr>
  76  * <tr>
  77  *    <td> streamrecorder_create() </td>
  78  *    <td> NONE </td>
  79  *    <td> CREATED </td>
  80  *    <td> SYNC </td>
  81  * </tr>
  82  * <tr>
  83  *    <td> streamrecorder_prepare() </td>
  84  *    <td> CREATED </td>
  85  *    <td> PREPARED </td>
  86  *    <td> SYNC </td>
  87  * </tr>
  88  * <tr>
  89  *    <td> streamrecorder_start() </td>
  90  *    <td> PREPARED / PAUSED </td>
  91  *    <td> RECORDING </td>
  92  *    <td> SYNC </td>
  93  * </tr>
  94  * <tr>
  95  *    <td> streamrecorder_pause() </td>
  96  *    <td> RECORDING </td>
  97  *    <td> PAUSED </td>
  98  *    <td> SYNC </td>
  99  * </tr>
 100  * <tr>
 101  *    <td> streamrecorder_commit() </td>
 102  *    <td> RECORDING/ PAUSED </td>
 103  *    <td> PREPARED </td>
 104  *    <td> SYNC </td>
 105  * </tr>
 106  * <tr>
 107  *    <td> streamrecorder_cancel() </td>
 108  *    <td> RECORDING/ PAUSED </td>
 109  *    <td> PREPARED </td>
 110  *    <td> SYNC </td>
 111  * </tr>
 112  * <tr>
 113  *    <td> streamrecorder_unprepare() </td>
 114  *    <td> PREPARED </td>
 115  *    <td> CREATED </td>
 116  *    <td> SYNC </td>
 117  * </tr>
 118  * <tr>
 119  *    <td> streamrecorder_destroy() </td>
 120  *    <td> CREATED </td>
 121  *    <td> NONE </td>
 122  *    <td> SYNC </td>
 123  * </tr>
 124  * </table></div>
 125  *
 126  * @subsection CAPI_MEDIA_STREAMRECORDER_LIFE_CYCLE_CALLBACK_OPERATIONS Callback(Event) Operations
 127  * The callback mechanism is used to notify the application about significant StreamRecorder events.
 128  * <div><table class="doxtable" >
 129  *     <tr>
 130  *        <th><b>REGISTER</b></th>
 131  *        <th><b>UNREGISTER</b></th>
 132  *        <th><b>CALLBACK</b></th>
 133  *        <th><b>DESCRIPTION</b></th>
 134  *     </tr>
 135  *     <tr>
 136  *        <td>streamrecorder_set_error_cb()</td>
 137  *        <td>streamrecorder_unset_error_cb()</td>
 138  *        <td>streamrecorder_error_cb()</td>
 139  *        <td>This callback is used to notify error has occurred</td>
 140  *     </tr>
 141  *</table></div>
 142  *
 143  * @subsection CAPI_MEDIA_STREAMRECORDER_FOREACH_OPERATIONS Foreach Operations
 144  * <div><table class="doxtable" >
 145  *     <tr>
 146  *        <th><b>FOREACH</b></th>
 147  *        <th><b>CALLBACK</b></th>
 148  *        <th><b>DESCRIPTION</b></th>
 149  *     </tr>
 150  *     <tr>
 151  *        <td>streamrecorder_foreach_supported_audio_encoder()</td>
 152  *        <td>streamrecorder_supported_audio_encoder_cb()</td>
 153  *        <td>Supported audio encoders</td>
 154  *     </tr>
 155  *     <tr>
 156  *        <td>streamrecorder_foreach_supported_video_encoder()</td>
 157  *        <td>streamrecorder_supported_video_encoder_cb()</td>
 158  *        <td>Supported video encoders</td>
 159  *     </tr>
 160  *     <tr>
 161  *        <td>streamrecorder_foreach_supported_file_format()</td>
 162  *        <td>streamrecorder_supported_file_format_cb()</td>
 163  *        <td>Supported file formats</td>
 164  *     </tr>
 165  *     <tr>
 166  *        <td>streamrecorder_foreach_supported_video_resolution()</td>
 167  *        <td>streamrecorder_supported_video_resolution_cb()</td>
 168  *        <td>Supported video resolutions</td>
 169  *     </tr>
 170  *</table></div>
 171  * @section CAPI_MEDIA_STREAMRECORDER_MODULE_FEATURE Related Features
 172  * This API is related with the following feature
 173  * - http://tizen.org/feature/multimedia.stream_recorder
 174  *
 175  * It is recommended to design feature related codes in your application for reliability.
 176  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.
 177  * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
 178  * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
 179  */
 180
 181
 182 /**
 183  * @defgroup CAPI_MEDIA_STREAMRECORDER_ATTRIBUTES_MODULE Attributes
 184  * @brief The @ref CAPI_MEDIA_STREAMRECORDER_ATTRIBUTES_MODULE API provides functions to fetch StreamRecorder attributes.
 185  * @ingroup CAPI_MEDIA_STREAMRECORDER_MODULE
 186  *
 187  * @section CAPI_MEDIA_STREAMRECORDER_ATTRIBUTES_MODULE_HEADER Required Header
 188  *   \#include <streamrecorder.h>
 189  *
 190  * @section CAPI_MEDIA_STREAMRECORDER_ATTRIBUTES_MODULE_OVERVIEW Overview
 191  * The StreamRecorder Attributes API provides functions to get/set basic StreamRecorder attributes.
 192  *
 193  * With the StreamRecorder Attributes API you are able to set and get StreamRecorder attributes like:
 194  * <ul>
 195  *  <li>File name</li>
 196  *  <li>File format</li>
 197  *  <li>Audio encoder</li>
 198  *  <li>Video encoder</li>
 199  *  <li>Recording size limit</li>
 200  *  <li>Recording time limit</li>
 201  *  <li>Audio samplerate</li>
 202  *  <li>Audio encoder bitrate</li>
 203  *  <li>Video encoder bitrate</li>
 204  *  <li>Audio channel</li>
 205  * </ul>
 206  *
 207  */
 208
 209 /**
 210  * @defgroup CAPI_MEDIA_STREAMRECORDER_CALLBACK_MODULE Callback
 211  * @brief The @ref CAPI_MEDIA_STREAMRECORDER_CALLBACK_MODULE API Callbacks from the StreamRecorder frameworks.
 212  * @ingroup CAPI_MEDIA_STREAMRECORDER_MODULE
 213  *
 214  * @section CAPI_MEDIA_STREAMRECORDER_CALLBACK_MODULE_HEADER Required Header
 215  *   \#include <streamrecorder.h>
 216  *
 217  * @section CAPI_MEDIA_STREAMRECORDER_CALLBACK_MODULE_OVERVIEW Overview
 218  * The StreamRecorder Callback API provides functions status.
 219  *
 220  */
 221
 222 /**
 223  * @ingroup CAPI_MEDIA_STREAMRECORDER_MODULE
 224  * @defgroup CAPI_MEDIA_STREAMRECORDER_CAPABILITY_MODULE Capability
 225  * @brief The @ref CAPI_MEDIA_STREAMRECORDER_CAPABILITY_MODULE API provides capability information of the StreamRecorder.
 226  * @section CAPI_MEDIA_STREAMRECORDER_CAPABILITY_MODULE_HEADER Required Header
 227  *   \#include <streamrecorder.h>
 228  *
 229  * @section CAPI_MEDIA_STREAMRECORDER_CAPABILITY_MODULE_OVERVIEW Overview
 230  * The StreamRecorder Capability API provides functions to obtain capability information of the StreamRecorder.
 231  *
 232  */
 233
 234 #endif /* __TIZEN_MEDIA_STREAMRECORDER_DOC_H__ */
 235
 236