1 /* 2 * Copyright (C) 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 #ifndef I_RECORDER_SERVICE_H 17 #define I_RECORDER_SERVICE_H 18 19 #include <string> 20 #include "recorder.h" 21 #include "refbase.h" 22 #include "surface.h" 23 24 namespace OHOS { 25 namespace Media { 26 class IRecorderService { 27 public: 28 virtual ~IRecorderService() = default; 29 30 /** 31 * @brief Sets a video source for recording. 32 * 33 * If this function is not called, the output file does not contain the video track. 34 * 35 * @param source Indicates the video source type. For details, see {@link VideoSourceType}. 36 * @param sourceId Indicates the video source ID. The value <b>-1</b> indicates an invalid ID and the setting fails. 37 * 38 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 39 * in {@link media_errors.h} otherwise. 40 * @since 1.0 41 * @version 1.0 42 */ 43 virtual int32_t SetVideoSource(VideoSourceType source, int32_t &sourceId) = 0; 44 45 /** 46 * @brief Sets a video encoder for recording. 47 * 48 * If this function is not called, the output file does not contain the video track. 49 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 50 * 51 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 52 * @param encoder Indicates the video encoder to set. 53 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 54 * in {@link media_errors.h} otherwise. 55 * @since 1.0 56 * @version 1.0 57 */ 58 virtual int32_t SetVideoEncoder(int32_t sourceId, VideoCodecFormat encoder) = 0; 59 60 /** 61 * @brief Sets the width and height of the video to record. 62 * 63 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 64 * 65 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 66 * @param width Indicates the video width to set. 67 * @param height Indicates the video height to set. 68 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 69 * in {@link media_errors.h} otherwise. 70 * @since 1.0 71 * @version 1.0 72 */ 73 virtual int32_t SetVideoSize(int32_t sourceId, int32_t width, int32_t height) = 0; 74 75 /** 76 * @brief Sets the frame rate of the video to record. 77 * 78 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 79 * 80 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 81 * @param frameRate Indicates the frame rate to set. 82 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 83 * in {@link media_errors.h} otherwise. 84 * @since 1.0 85 * @version 1.0 86 */ 87 virtual int32_t SetVideoFrameRate(int32_t sourceId, int32_t frameRate) = 0; 88 89 /** 90 * @brief Sets the encoding bit rate of the video to record. 91 * 92 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. 93 * 94 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 95 * @param rate Indicates the encoding bit rate to set. 96 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 97 * in {@link media_errors.h} otherwise. 98 * @since 1.0 99 * @version 1.0 100 */ 101 virtual int32_t SetVideoEncodingBitRate(int32_t sourceId, int32_t rate) = 0; 102 103 /** 104 * @brief Sets the video capture rate. 105 * 106 * This function must be called after {@link SetVideoSource} but before {@link Prepare}. It is valid when the 107 * video source is YUV or RGB. 108 * 109 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 110 * @param fps Indicates the rate at which frames are captured per second. 111 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 112 * in {@link media_errors.h} otherwise. 113 * @since 1.0 114 * @version 1.0 115 */ 116 virtual int32_t SetCaptureRate(int32_t sourceId, double fps) = 0; 117 118 /** 119 * @brief Obtains the surface of the video source. 120 * 121 * @param sourceId Indicates the video source ID, which can be obtained from {@link SetVideoSource}. 122 * @return Returns the pointer to the surface. 123 * @since 1.0 124 * @version 1.0 125 */ 126 virtual sptr<OHOS::Surface> GetSurface(int32_t sourceId) = 0; 127 128 /** 129 * @brief Sets the audio source for recording. 130 * 131 * If this function is not called, the output file does not contain the audio track. 132 * 133 * @param source Indicates the audio source type. For details, see {@link AudioSourceType}. 134 * @param sourceId Indicates the audio source ID. The value <b>-1</b> indicates an invalid ID and the setting fails. 135 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 136 * in {@link media_errors.h} otherwise. 137 * @since 1.0 138 * @version 1.0 139 */ 140 virtual int32_t SetAudioSource(AudioSourceType source, int32_t &sourceId) = 0; 141 142 /** 143 * @brief Sets an audio encoder for recording. 144 * 145 * If this function is not called, the output file does not contain the audio track. 146 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 147 * 148 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 149 * @param encoder Indicates the audio encoder to set. 150 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 151 * in {@link media_errors.h} otherwise. 152 * @since 1.0 153 * @version 1.0 154 */ 155 virtual int32_t SetAudioEncoder(int32_t sourceId, AudioCodecFormat encoder) = 0; 156 157 /** 158 * @brief Sets the audio sampling rate for recording. 159 * 160 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 161 * 162 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 163 * @param rate Indicates the sampling rate of the audio per second. 164 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 165 * in {@link media_errors.h} otherwise. 166 * @since 1.0 167 * @version 1.0 168 */ 169 virtual int32_t SetAudioSampleRate(int32_t sourceId, int32_t rate) = 0; 170 171 /** 172 * @brief Sets the number of audio channels to record. 173 * 174 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 175 * 176 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 177 * @param num Indicates the number of audio channels to set. 178 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 179 * in {@link media_errors.h} otherwise. 180 * @since 1.0 181 * @version 1.0 182 */ 183 virtual int32_t SetAudioChannels(int32_t sourceId, int32_t num) = 0; 184 185 /** 186 * @brief Sets the encoding bit rate of the audio to record. 187 * 188 * This function must be called after {@link SetAudioSource} but before {@link Prepare}. 189 * 190 * @param sourceId Indicates the audio source ID, which can be obtained from {@link SetAudioSource}. 191 * @param bitRate Indicates the audio encoding bit rate, in bit/s. 192 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 193 * in {@link media_errors.h} otherwise. 194 * @since 1.0 195 * @version 1.0 196 */ 197 virtual int32_t SetAudioEncodingBitRate(int32_t sourceId, int32_t bitRate) = 0; 198 199 /** 200 * @brief Sets a data source for recording. 201 * 202 * If this function is not called, the output file does not contain the data track. 203 * 204 * @param sourceId Indicates the data source ID. The value <b>-1</b> indicates an invalid ID and the setting fails. 205 * 206 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 207 * in {@link media_errors.h} otherwise. 208 * @since 1.0 209 * @version 1.0 210 */ 211 virtual int32_t SetDataSource(DataSourceType dataType, int32_t &sourceId) = 0; 212 213 /** 214 * @brief Sets the maximum duration of a recorded file, in seconds. 215 * 216 * This method must be called before {@link Prepare}. If the setting is valid, 217 * {@link RECORDER_INFO_MAX_DURATION_APPROACHING} is reported through {@link OnInfo} in the {@link RecorderCallback} 218 * class when only one second or 10% is left to reach the allowed duration. 219 * If the recording output file is set by calling {@link SetOutputFile}, call {@link SetNextOutputFile} to set the 220 * next output file. Otherwise, the current file will be overwritten when the allowed duration is reached. 221 * 222 * @param duration Indicates the maximum recording duration to set. If the value is <b>0</b> or a negative number, 223 * a failure message is returned. The default duration is 60s. 224 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 225 * in {@link media_errors.h} otherwise. 226 * @since 1.0 227 * @version 1.0 228 */ 229 virtual int32_t SetMaxDuration(int32_t duration) = 0; 230 231 /** 232 * @brief Sets the output file format. 233 * 234 * This function must be called before {@link Prepare}. 235 * 236 * @param format Indicates the output file format. For details, see {@link OutputFormatType}. 237 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 238 * in {@link media_errors.h} otherwise. 239 * @since 1.0 240 * @version 1.0 241 */ 242 virtual int32_t SetOutputFormat(OutputFormatType format) = 0; 243 244 /** 245 * @brief Sets the file descriptor (FD) of the output file. 246 * 247 * This function must be called before {@link Prepare}. 248 * 249 * @param fd Indicates the FD of the file. 250 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 251 * in {@link media_errors.h} otherwise. 252 * @since 1.0 253 * @version 1.0 254 */ 255 virtual int32_t SetOutputFile(int32_t fd) = 0; 256 257 /** 258 * @brief Sets the FD of the next output file. 259 * 260 * If {@link SetOutputFile} is successful, call this function to set the FD of the next output file after 261 * {@link RECORDER_INFO_MAX_DURATION_APPROACHING} or {@link RECORDER_INFO_MAX_FILESIZE_APPROACHING} is received. 262 * 263 * @param fd Indicates the FD of the next output file. 264 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 265 * in {@link media_errors.h} otherwise. 266 * @since 1.0 267 * @version 1.0 268 */ 269 virtual int32_t SetNextOutputFile(int32_t fd) = 0; 270 271 /** 272 * @brief Sets the maximum size of a recorded file, in bytes. 273 * 274 * This function must be called before {@link Prepare}. If the setting is valid, 275 * {@link RECORDER_INFO_MAX_DURATION_APPROACHING} is reported through {@link OnInfo} in the {@link RecorderCallback} 276 * class when only 100 KB or 10% is left to reach the allowed size. 277 * If the recording output file is set by calling {@link SetOutputFile}, call {@link SetNextOutputFile} to set the 278 * next output file. Otherwise, when the allowed size is reached, the current file will be overwritten. If 279 * <b>MaxDuration</b> is also set by calling {@link SetMaxDuration}, <b>MaxDuration</b> or <b>MaxFileSize</b> 280 * prevails depending on which of them is first satisfied. 281 * 282 * @param size Indicates the maximum file size to set. If the value is <b>0</b> or a negative number, a failure 283 * message is returned. 284 * By default, the maximum size of a single file supported by the current file system is used as the limit. 285 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 286 * in {@link media_errors.h} otherwise. 287 * @since 1.0 288 * @version 1.0 289 */ 290 virtual int32_t SetMaxFileSize(int64_t size) = 0; 291 292 /** 293 * @brief Set and store the geodata (latitude and longitude) in the output file. 294 * This method should be called before prepare(). The geodata is stored in udta box if 295 * the output format is OutputFormat.THREE_GPP or OutputFormat.MPEG_4, 296 * and is ignored for other output formats. 297 * 298 * @param latitude float: latitude in degrees. Its value must be in the range [-90, 90]. 299 * @param longitude float: longitude in degrees. Its value must be in the range [-180, 180]. 300 * @since openharmony 3.1 301 * @version 1.0 302 */ 303 virtual void SetLocation(float latitude, float longitude) = 0; 304 305 /** 306 * @brief set the orientation hint in output file, and for the file to playback. mp4 support. 307 * the range of orientation should be {0, 90, 180, 270}, default is 0. 308 * 309 * @param rotation int32_t: should be {0, 90, 180, 270}, default is 0. 310 * @since openharmony 3.1 311 * @version 1.0 312 */ 313 virtual void SetOrientationHint(int32_t rotation) = 0; 314 315 /** 316 * @brief Registers a recording listener. 317 * 318 * This function must be called before {@link Prepare}. 319 * 320 * @param callback Indicates the recording listener to register. For details, see {@link RecorderCallback}. 321 * @return Returns {@link SUCCESS} if the listener is registered; returns an error code defined 322 * in {@link media_errors.h} otherwise. 323 * @since 1.0 324 * @version 1.0 325 */ 326 virtual int32_t SetRecorderCallback(const std::shared_ptr<RecorderCallback> &callback) = 0; 327 328 /** 329 * @brief Prepares for recording. 330 * 331 * This function must be called before {@link Start}. 332 * 333 * @return Returns {@link SUCCESS} if the preparation is successful; returns an error code defined 334 * in {@link media_errors.h} otherwise. 335 * @since 1.0 336 * @version 1.0 337 */ 338 virtual int32_t Prepare() = 0; 339 340 /** 341 * @brief Starts recording. 342 * 343 * This function must be called after {@link Prepare}. 344 * 345 * @return Returns {@link SUCCESS} if the recording is started; returns an error code defined 346 * in {@link media_errors.h} otherwise. 347 * @since 1.0 348 * @version 1.0 349 */ 350 virtual int32_t Start() = 0; 351 352 /** 353 * @brief Pauses recording. 354 * 355 * After {@link Start} is called, you can call this function to pause recording. 356 * 357 * @return Returns {@link SUCCESS} if the recording is paused; returns an error code defined 358 * in {@link media_errors.h} otherwise. 359 * @since 1.0 360 * @version 1.0 361 */ 362 virtual int32_t Pause() = 0; 363 364 /** 365 * @brief Resumes recording. 366 * 367 * You can call this function to resume recording after {@link Pause} is called. 368 * 369 * @return Returns {@link SUCCESS} if the recording is resumed; returns an error code defined 370 * in {@link media_errors.h} otherwise. 371 * @since 1.0 372 * @version 1.0 373 */ 374 virtual int32_t Resume() = 0; 375 376 /** 377 * @brief Stops recording. 378 * 379 * @param block Indicates the stop mode. The value <b>true</b> indicates that the processing stops after all caches 380 * are processed, and <b>false</b> indicates that the processing stops immediately and all caches are discarded. 381 * @return Returns {@link SUCCESS} if the recording is stopped; returns an error code defined 382 * in {@link media_errors.h} otherwise. 383 * @since 1.0 384 * @version 1.0 385 */ 386 virtual int32_t Stop(bool block) = 0; 387 388 /** 389 * @brief Resets the recording. 390 * 391 * After the function is called, add a recording source by calling {@link SetVideoSource} or {@link SetAudioSource}, 392 * set related parameters, and call {@link Start} to start recording again after {@link Prepare} is called. 393 * 394 * @return Returns {@link SUCCESS} if the recording is reset; returns an error code defined 395 * in {@link media_errors.h} otherwise. 396 * @since 1.0 397 * @version 1.0 398 */ 399 virtual int32_t Reset() = 0; 400 401 /** 402 * @brief Releases recording resources. 403 * 404 * @return Returns {@link SUCCESS} if recording resources are released; returns an error code defined 405 * in {@link media_errors.h} otherwise. 406 * @since 1.0 407 * @version 1.0 408 */ 409 virtual int32_t Release() = 0; 410 411 /** 412 * @brief Manually splits a video. 413 * 414 * This function must be called after {@link Start}. After this function is called, the file is split based on the 415 * manual split type. After the manual split is complete, the initial split type is used. This function can be 416 * called again only after {@link RECORDER_INFO_FILE_SPLIT_FINISHED} is reported. 417 * 418 * @param type Indicates the file split type. For details, see {@link FileSplitType}. 419 * @param timestamp Indicates the file split timestamp. This parameter is not supported currently and can be set to 420 * <b>-1</b>. The recording module splits a file based on the call time. 421 * @param duration Indicates the duration for splitting the file. 422 * @return Returns {@link SUCCESS} if the video is manually split; returns an error code defined 423 * in {@link media_errors.h} otherwise. 424 * @since 1.0 425 * @version 1.0 426 */ 427 virtual int32_t SetFileSplitDuration(FileSplitType type, int64_t timestamp, uint32_t duration) = 0; 428 429 /** 430 * @brief Sets an extended parameter for recording, for example, {@link RECORDER_PRE_CACHE_DURATION}. 431 * 432 * @param sourceId Indicates the data source ID. The value <b>-1</b> indicates all sources. 433 * @param format Indicates the string key and value. For details, see {@link Format} and 434 * {@link RECORDER_PRE_CACHE_DURATION}. 435 * @return Returns {@link SUCCESS} if the setting is successful; returns an error code defined 436 * in {@link media_errors.h} otherwise. 437 * @since 1.0 438 * @version 1.0 439 */ 440 virtual int32_t SetParameter(int32_t sourceId, const Format &format) = 0; 441 442 /** 443 * @brief Called periodically during recording. Notifies the recording module that the application is running 444 * normally. 445 * 446 * @return Returns {@link SUCCESS} if notification complete; returns an error code defined 447 * in {@link media_errors.h} otherwise. 448 * @since 1.0 449 * @version 1.0 450 */ 451 virtual int32_t HeartBeat() = 0; 452 }; 453 } // namespace Media 454 } // namespace OHOS 455 #endif // I_RECORDER_SERVICE_H 456