1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup MultiMedia_Recorder 18 * @{ 19 * 20 * @brief Defines the <b>Recorder</b> class and provides functions for audio and video recording. 21 * 22 * 23 * @since 1.0 24 * @version 1.0 25 */ 26 27 /** 28 * @file recorder.h 29 * 30 * @brief Declares the <b>Recorder</b> class for audio and video recording. 31 * 32 * 33 * @since 1.0 34 * @version 1.0 35 */ 36 37 #ifndef RECORDER_H 38 #define RECORDER_H 39 40 #include <cstddef> 41 #include <cstdint> 42 #include <time.h> 43 #include <memory> 44 45 #include "media_errors.h" 46 #include "media_info.h" 47 #include "format.h" 48 #include "surface.h" 49 50 namespace OHOS { 51 namespace Media { 52 using std::string; 53 using OHOS::Surface; 54 55 /** 56 * This constant can be used as the value of {@link Format} in {@link SetParameter} to configure the duration for 57 * storing recorded data in the cache. 58 */ 59 const string RECORDER_PRE_CACHE_DURATION = "pre-cache-duration"; 60 const string RECORDER_RECORD_SPEED = "record-speed"; 61 62 /** 63 * @brief Enumerates video source types. 64 * 65 * @since 1.0 66 * @version 1.0 67 */ 68 enum VideoSourceType : int32_t { 69 /** YUV video data provided through {@link Surface} */ 70 VIDEO_SOURCE_SURFACE_YUV = 0, 71 /** RGB video data provided through {@link Surface} */ 72 VIDEO_SOURCE_SURFACE_RGB, 73 /** Raw encoded data provided through {@link Surface} */ 74 VIDEO_SOURCE_SURFACE_ES, 75 /** Invalid value */ 76 VIDEO_SOURCE_BUTT 77 }; 78 79 /** 80 * @brief Enumerates data source types. 81 * 82 * @since 1.0 83 * @version 1.0 84 */ 85 enum DataSourceType : int32_t { 86 /** meta data source */ 87 METADATA = 0 88 }; 89 90 /** 91 * @brief Enumerates output file formats. 92 * 93 * @since 1.0 94 * @version 1.0 95 */ 96 enum OutputFormatType : int32_t { 97 /** Default format */ 98 FORMAT_DEFAULT = 0, 99 /** MPEG4 format */ 100 FORMAT_MPEG_4, 101 /** TS format */ 102 FORMAT_TS, 103 }; 104 105 /** 106 * @brief Enumerates file split types. 107 * 108 * @since 1.0 109 * @version 1.0 110 */ 111 enum FileSplitType : int32_t { 112 /** Delayed/Backward split */ 113 FILE_SPLIT_POST = 0, 114 /** Advanced/Forward split */ 115 FILE_SPLIT_PRE, 116 /** Normal split */ 117 FILE_SPLIT_NORMAL 118 }; 119 120 /** 121 * @brief Provides listeners for recording errors and information events. 122 * 123 * @since 1.0 124 * @version 1.0 125 */ 126 class RecorderCallback { 127 public: 128 129 /** 130 * @brief Enumerates recording information types. 131 * 132 * @since 1.0 133 * @version 1.0 134 */ 135 enum RecorderInfoType : int32_t { 136 /** 137 * The recording duration is reaching the threshold specified by {@link SetMaxDuration}. This type of 138 * information is reported when only one second or 10% is left to reach the allowed duration. 139 */ 140 RECORDER_INFO_MAX_DURATION_APPROACHING = 0, 141 /** 142 * The recorded file size is reaching the threshold specified by {@link SetMaxFileSize}. This type of 143 * information is reported when only 100 KB or 10% is left to reach the allowed size. 144 */ 145 RECORDER_INFO_MAX_FILESIZE_APPROACHING, 146 /** 147 * The threshold specified by {@link SetMaxDuration} is reached, and the recording ends. 148 * Before calling {@link SetNextOutputFile}, you must close the file. 149 */ 150 RECORDER_INFO_MAX_DURATION_REACHED, 151 /** 152 * The threshold specified by {@link SetMaxFileSize} is reached, and the recording ends. 153 * Before calling {@link SetNextOutputFile}, you must close the file. 154 */ 155 RECORDER_INFO_MAX_FILESIZE_REACHED, 156 /** Recording started for the next output file. */ 157 RECORDER_INFO_NEXT_OUTPUT_FILE_STARTED, 158 /** Manual file split completed. */ 159 RECORDER_INFO_FILE_SPLIT_FINISHED, 160 /** The start time position of the recording file is not supported. */ 161 RECORDER_INFO_FILE_START_TIME_MS, 162 /** Next file fd is needed but not set. */ 163 RECORDER_INFO_NEXT_FILE_FD_NOT_SET, 164 /** No frame data is sent to recorder. */ 165 RECORDER_INFO_NO_FRAME_DATA 166 }; 167 168 /** 169 * @brief Enumerates recording error types. 170 * 171 * @since 1.0 172 * @version 1.0 173 */ 174 enum RecorderErrorType : int32_t { 175 /* create file failed */ 176 RECORDER_ERROR_CREATE_FILE_FAIL = 0, 177 /* write file failed */ 178 RECORDER_ERROR_WRITE_FILE_FAIL, 179 /* close file failed */ 180 RECORDER_ERROR_CLOSE_FILE_FAIL, 181 /* read data failed or time out */ 182 RECORDER_ERROR_READ_DATA_ERROR, 183 /* rec internal operation fail, must stop rec */ 184 RECORDER_ERROR_INTERNAL_OPERATION_FAIL, 185 /** Unknown error */ 186 RECORDER_ERROR_UNKNOWN 187 }; 188 189 /** 190 * @brief Called when an error occurs during recording. This callback is used to report recording errors. 191 * 192 * @param errorType Indicates the error type. For details, see {@link RecorderErrorType}. 193 * @param errorCode Indicates the error code. 194 * @since 1.0 195 * @version 1.0 196 */ 197 virtual void OnError(int32_t errorType, int32_t errorCode) = 0; 198 199 /** 200 * @brief Called when an information event occurs during recording. This callback is used to report recording 201 * information. 202 * 203 * @param type Indicates the information type. For details, see {@link RecorderInfoType}. 204 * @param extra Indicates other information, for example, the start time position of a recording file. 205 * @since 1.0 206 * @version 1.0 207 */ 208 virtual void OnInfo(int32_t type, int32_t extra) = 0; 209 }; 210 211 /** 212 * @brief Provides functions for audio and video recording. 213 * 214 * @since 1.0 215 * @version 1.0 216 */ 217 class Recorder { 218 public: 219 Recorder(); 220 virtual ~Recorder(); 221 222 /** 223 * @brief Sets a video source for recording. 224 * 225 * If this function is not called, the output file does not contain the video track. 226 * 227 * @param source Indicates the video source type. For details, see {@link VideoSourceType}. 228 * @param sourceId Indicates the video source ID. The value <b>-1</b> indicates an invalid ID and the setting fails. 229 * 230 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 231 * in {@link media_errors.h} otherwise. 232 * @since 1.0 233 * @version 1.0 234 */ 235 int32_t SetVideoSource(VideoSourceType source, int32_t &sourceId); 236 237 /** 238 * @brief Sets a video encoder for recording. 239 * 240 * If this function is not called, the output file does not contain the video track. \n 241 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. \n 242 * 243 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 244 * @param encoder Indicates the video encoder to set. 245 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 246 * in {@link media_errors.h} otherwise. 247 * @since 1.0 248 * @version 1.0 249 */ 250 int32_t SetVideoEncoder(int32_t sourceId, VideoCodecFormat encoder); 251 252 /** 253 * @brief Sets the width and height of the video to record. 254 * 255 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 256 * 257 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 258 * @param width Indicates the video width to set. 259 * @param height Indicates the video height to set. 260 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 261 * in {@link media_errors.h} otherwise. 262 * @since 1.0 263 * @version 1.0 264 */ 265 int32_t SetVideoSize(int32_t sourceId, int32_t width, int32_t height); 266 267 /** 268 * @brief Sets the frame rate of the video to record. 269 * 270 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 271 * 272 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 273 * @param frameRate Indicates the frame rate to set. 274 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 275 * in {@link media_errors.h} otherwise. 276 * @since 1.0 277 * @version 1.0 278 */ 279 int32_t SetVideoFrameRate(int32_t sourceId, int32_t frameRate); 280 281 /** 282 * @brief Sets the encoding bit rate of the video to record. 283 * 284 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 285 * 286 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 287 * @param rate Indicates the encoding bit rate to set. 288 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 289 * in {@link media_errors.h} otherwise. 290 * @since 1.0 291 * @version 1.0 292 */ 293 int32_t SetVideoEncodingBitRate(int32_t sourceId, int32_t rate); 294 295 /** 296 * @brief Sets the video capture rate. 297 * 298 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. It is valid when the 299 * video source is YUV or RGB. 300 * 301 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 302 * @param fps Indicates the rate at which frames are captured per second. 303 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 304 * in {@link media_errors.h} otherwise. 305 * @since 1.0 306 * @version 1.0 307 */ 308 int32_t SetCaptureRate(int32_t sourceId, double fps); 309 310 /** 311 * @brief Obtains the surface of the video source. 312 * 313 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 314 * @return Returns the pointer to the surface. 315 * @since 1.0 316 * @version 1.0 317 */ 318 std::shared_ptr<OHOS::Surface> GetSurface(int32_t sourceId); 319 320 /** 321 * @brief Sets the audio source for recording. 322 * 323 * If this function is not called, the output file does not contain the audio track. 324 * 325 * @param source Indicates the audio source type. For details, see {@link AudioSourceType}. 326 * @param sourceId Indicates the audio source ID. The value <b>-1</b> indicates an invalid ID and the setting fails. 327 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 328 * in {@link media_errors.h} otherwise. 329 * @since 1.0 330 * @version 1.0 331 */ 332 int32_t SetAudioSource(AudioSourceType source, int32_t &sourceId); 333 334 /** 335 * @brief Sets an audio encoder for recording. 336 * 337 * If this function is not called, the output file does not contain the audio track. \n 338 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. \n 339 * 340 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 341 * @param encoder Indicates the audio encoder to set. 342 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 343 * in {@link media_errors.h} otherwise. 344 * @since 1.0 345 * @version 1.0 346 */ 347 int32_t SetAudioEncoder(int32_t sourceId, AudioCodecFormat encoder); 348 349 /** 350 * @brief Sets the audio sampling rate for recording. 351 * 352 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 353 * 354 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 355 * @param rate Indicates the sampling rate of the audio per second. 356 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 357 * in {@link media_errors.h} otherwise. 358 * @since 1.0 359 * @version 1.0 360 */ 361 int32_t SetAudioSampleRate(int32_t sourceId, int32_t rate); 362 363 /** 364 * @brief Sets the number of audio channels to record. 365 * 366 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 367 * 368 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 369 * @param num Indicates the number of audio channels to set. 370 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 371 * in {@link media_errors.h} otherwise. 372 * @since 1.0 373 * @version 1.0 374 */ 375 int32_t SetAudioChannels(int32_t sourceId, int32_t num); 376 377 /** 378 * @brief Sets the encoding bit rate of the audio to record. 379 * 380 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 381 * 382 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 383 * @param bitRate Indicates the audio encoding bit rate, in bit/s. 384 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 385 * in {@link media_errors.h} otherwise. 386 * @since 1.0 387 * @version 1.0 388 */ 389 int32_t SetAudioEncodingBitRate(int32_t sourceId, int32_t bitRate); 390 391 /** 392 * @brief Sets a data source for recording. 393 * 394 * If this function is not called, the output file does not contain the data track. 395 * 396 * @param sourceId Indicates the data source ID. The value <b>-1</b> indicates an invalid ID and the setting fails. 397 * 398 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 399 * in {@link media_errors.h} otherwise. 400 * @since 1.0 401 * @version 1.0 402 */ 403 int32_t SetDataSource(DataSourceType dataType, int32_t &sourceId); 404 405 /** 406 * @brief Sets the maximum duration of a recorded file, in seconds. 407 * 408 * This method must be called before {@link Prepare}. If the setting is valid, 409 * {@link RECORDER_INFO_MAX_DURATION_APPROACHING} is reported through {@link OnInfo} in the {@link RecorderCallback} 410 * class when only one second or 10% is left to reach the allowed duration. \n 411 * If the recording output file is set by calling {@link SetOutputFile}, call {@link SetNextOutputFile} to set the 412 * next output file. Otherwise, the current file will be overwritten when the allowed duration is reached. \n 413 * 414 * @param duration Indicates the maximum recording duration to set. If the value is <b>0</b> or a negative number, 415 * a failure message is returned. The default duration is 60s. 416 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 417 * in {@link media_errors.h} otherwise. 418 * @since 1.0 419 * @version 1.0 420 */ 421 int32_t SetMaxDuration(int32_t duration); 422 423 /** 424 * @brief Sets the output file format. 425 * 426 * This function must be called before {@link Prepare}. 427 * 428 * @param format Indicates the output file format. For details, see {@link OutputFormatType}. 429 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 430 * in {@link media_errors.h} otherwise. 431 * @since 1.0 432 * @version 1.0 433 */ 434 int32_t SetOutputFormat(OutputFormatType format); 435 436 /** 437 * @brief Sets the output file path. 438 * 439 * This function must be called before {@link Prepare} and One of them {@link SetOutputFile} must be set. 440 * 441 * @param path Indicates the output file path. 442 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 443 * in {@link media_errors.h} otherwise. 444 * @since 1.0 445 * @version 1.0 446 */ 447 int32_t SetOutputPath(const string &path); 448 449 /** 450 * @brief Sets the file descriptor (FD) of the output file. 451 * 452 * This function must be called before {@link Prepare}. 453 * 454 * @param fd Indicates the FD of the file. 455 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 456 * in {@link media_errors.h} otherwise. 457 * @since 1.0 458 * @version 1.0 459 */ 460 int32_t SetOutputFile(int32_t fd); 461 462 /** 463 * @brief Sets the FD of the next output file. 464 * 465 * If {@link SetOutputFile} is successful, call this function to set the FD of the next output file after 466 * {@link RECORDER_INFO_MAX_DURATION_APPROACHING} or {@link RECORDER_INFO_MAX_FILESIZE_APPROACHING} is received. 467 * 468 * @param fd Indicates the FD of the next output file. 469 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 470 * in {@link media_errors.h} otherwise. 471 * @since 1.0 472 * @version 1.0 473 */ 474 int32_t SetNextOutputFile(int32_t fd); 475 476 /** 477 * @brief Sets the maximum size of a recorded file, in bytes. 478 * 479 * This function must be called before {@link Prepare}. If the setting is valid, 480 * {@link RECORDER_INFO_MAX_DURATION_APPROACHING} is reported through {@link OnInfo} in the {@link RecorderCallback} 481 * class when only 100 KB or 10% is left to reach the allowed size. \n 482 * If the recording output file is set by calling {@link SetOutputFile}, call {@link SetNextOutputFile} to set the 483 * next output file. Otherwise, when the allowed size is reached, the current file will be overwritten. If 484 * <b>MaxDuration</b> is also set by calling {@link SetMaxDuration}, <b>MaxDuration</b> or <b>MaxFileSize</b> 485 * prevails depending on which of them is first satisfied. 486 * 487 * @param size Indicates the maximum file size to set. If the value is <b>0</b> or a negative number, a failure 488 * message is returned. 489 * By default, the maximum size of a single file supported by the current file system is used as the limit. 490 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 491 * in {@link media_errors.h} otherwise. 492 * @since 1.0 493 * @version 1.0 494 */ 495 int32_t SetMaxFileSize(int64_t size); 496 497 /** 498 * @brief Registers a recording listener. 499 * 500 * This function must be called before {@link Prepare}. 501 * 502 * @param callback Indicates the recording listener to register. For details, see {@link RecorderCallback}. 503 * @return Returns {@link SUCCESS} if the listener is registered; returns an error code defined 504 * in {@link media_errors.h} otherwise. 505 * @since 1.0 506 * @version 1.0 507 */ 508 int32_t SetRecorderCallback(const std::shared_ptr<RecorderCallback> &callback); 509 510 /** 511 * @brief Prepares for recording. 512 * 513 * This function must be called before {@link Start}. 514 * 515 * @return Returns {@link SUCCESS} if the preparation is successful; returns an error code defined 516 * in {@link media_errors.h} otherwise. 517 * @since 1.0 518 * @version 1.0 519 */ 520 int32_t Prepare(); 521 522 /** 523 * @brief Starts recording. 524 * 525 * This function must be called after {@link Prepare}. 526 * 527 * @return Returns {@link SUCCESS} if the recording is started; returns an error code defined 528 * in {@link media_errors.h} otherwise. 529 * @since 1.0 530 * @version 1.0 531 */ 532 int32_t Start(); 533 534 /** 535 * @brief Pauses recording. 536 * 537 * After {@link Start} is called, you can call this function to pause recording. The audio and video source streams 538 * are not paused, and source data is discarded. 539 * 540 * @return Returns {@link SUCCESS} if the recording is paused; returns an error code defined 541 * in {@link media_errors.h} otherwise. 542 * @since 1.0 543 * @version 1.0 544 */ 545 int32_t Pause(); 546 547 /** 548 * @brief Resumes recording. 549 * 550 * You can call this function to resume recording after {@link Pause} is called. 551 * 552 * @return Returns {@link SUCCESS} if the recording is resumed; returns an error code defined 553 * in {@link media_errors.h} otherwise. 554 * @since 1.0 555 * @version 1.0 556 */ 557 int32_t Resume(); 558 559 /** 560 * @brief Stops recording. 561 * 562 * @param block Indicates the stop mode. The value <b>true</b> indicates that the processing stops after all caches 563 * are processed, and <b>false</b> indicates that the processing stops immediately and all caches are discarded. 564 * @return Returns {@link SUCCESS} if the recording is stopped; returns an error code defined 565 * in {@link media_errors.h} otherwise. 566 * @since 1.0 567 * @version 1.0 568 */ 569 int32_t Stop(bool block); 570 571 /** 572 * @brief Resets the recording. 573 * 574 * After the function is called, add a recording source by calling {@link SetVideoSource} or {@link SetAudioSource}, 575 * set related parameters, and call {@link Start} to start recording again after {@link Prepare} is called. 576 * 577 * @return Returns {@link SUCCESS} if the recording is reset; returns an error code defined 578 * in {@link media_errors.h} otherwise. 579 * @since 1.0 580 * @version 1.0 581 */ 582 int32_t Reset(); 583 584 /** 585 * @brief Releases recording resources. 586 * 587 * @return Returns {@link SUCCESS} if recording resources are released; returns an error code defined 588 * in {@link media_errors.h} otherwise. 589 * @since 1.0 590 * @version 1.0 591 */ 592 int32_t Release(); 593 594 /** 595 * @brief Manually splits a video. 596 * 597 * This function must be called after {@link Start}. After this function is called, the file is split based on the 598 * manual split type. After the manual split is complete, the initial split type is used. This function can be 599 * called again only after {@link RECORDER_INFO_FILE_SPLIT_FINISHED} is reported. 600 * 601 * @param type Indicates the file split type. For details, see {@link FileSplitType}. 602 * @param timestamp Indicates the file split timestamp. This parameter is not supported currently and can be set to 603 * <b>-1</b>. The recording module splits a file based on the call time. 604 * @param duration Indicates the duration for splitting the file. 605 * @return Returns {@link SUCCESS} if the video is manually split; returns an error code defined 606 * in {@link media_errors.h} otherwise. 607 * @since 1.0 608 * @version 1.0 609 */ 610 int32_t SetFileSplitDuration(FileSplitType type, int64_t timestamp, uint32_t duration); 611 612 /** 613 * @brief Sets an extended parameter for recording, for example, {@link RCORDER_PRE_CACHE_DURATION}. 614 * 615 * @param sourceId Indicates the data source ID. The value <b>-1</b> indicates all sources. 616 * @param format Indicates the string key and value. For details, see {@link Format} and 617 * {@link RCORDER_PRE_CACHE_DURATION}. 618 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 619 * in {@link media_errors.h} otherwise. 620 * @since 1.0 621 * @version 1.0 622 */ 623 int32_t SetParameter(int32_t sourceId, const Format &format); 624 625 private: 626 class RecorderClient; 627 std::unique_ptr<RecorderClient> client_; 628 }; 629 } // namespace Media 630 } // namespace OHOS 631 #endif // RECORDER_H 632