2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FMediaAudioRecorder.h
20 * @brief This is the header file for the %AudioRecorder class.
22 * This header file contains the declarations of the %AudioRecorder class.
25 #ifndef _FMEDIA_AUDIO_RECORDER_H_
26 #define _FMEDIA_AUDIO_RECORDER_H_
28 #include <FMediaAudioRecorderTypes.h>
29 #include <FMediaIAudioRecorderEventListener.h>
30 #include <FMediaTypes.h>
32 namespace Tizen { namespace Media
35 class _AudioRecorderImpl;
36 class IAudioStreamFilter;
39 * @class AudioRecorder
40 * @brief This class records the audio data into a file.
44 * The %AudioRecorder class records the audio data from an input device source to the storage device. The
45 * selection of the input device source depends upon the current device status. For example, if a headset device is
46 * connected, it is selected as an input source. The audio recording format, the maximum recording time, and the
47 * maximum recording size can be set using the methods available in this class.
49 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/recording_audio.htm">Recording Audio</a>.
51 * The following example demonstrates how to use the %AudioRecorder class.
60 * using namespace Tizen::Base;
61 * using namespace Tizen::Io;
62 * using namespace Tizen::Media;
64 * class AudioRecorderSample
65 * : public IAudioRecorderEventListener
72 * virtual void OnAudioRecorderStopped(result r) {}
73 * virtual void OnAudioRecorderCanceled(result r) {}
74 * virtual void OnAudioRecorderPaused(result r) {}
75 * virtual void OnAudioRecorderStarted(result r) {}
76 * virtual void OnAudioRecorderEndReached(RecordingEndCondition endCondition) {}
77 * virtual void OnAudioRecorderClosed(result r) {}
78 * virtual void OnAudioRecorderErrorOccurred(RecorderErrorReason r) {}
81 * AudioRecorder __recorder;
85 * AudioRecorderSample::Start(void)
88 * String destFilePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.amr";
90 * r = __recorder.Construct(*this);
96 * r = __recorder.CreateAudioFile(destFilePath, true);
102 * r = __recorder.Record();
112 * AudioRecorderSample::Stop(void)
115 * __recorder.Close();
122 class _OSP_EXPORT_ AudioRecorder
123 : public Tizen::Base::Object
128 * This is the default constructor for this class.
132 * @remarks The object is not fully constructed after this constructor is called.
133 * For full construction, the Construct() method must be called right after calling this constructor.
138 * This is the destructor for this class. @n
139 * All allocated resources are released by this method. This method must be called in the same thread in
140 * which the Construct() method is called. This polymorphic destructor should be overridden if required.
141 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
146 virtual ~AudioRecorder(void);
151 * Initializes this instance of %AudioRecorder with the specified listener.
155 * @return An error code
156 * @param[in] listener An instance of IAudioRecorderEventListener
157 * @exception E_SUCCESS The method is successful.
158 * @exception E_SYSTEM A system error has occurred.
159 * @exception E_OUT_OF_MEMORY The memory is insufficient.
160 * @exception E_UNSUPPORTED_OPERATION This audio recorder usage is not supported.
161 * @exception E_DEVICE_BUSY The recorder is under use by other application or already used in this application.
163 result Construct(IAudioRecorderEventListener& listener);
166 * Creates an audio file for the recording.
169 * @brief <i> [Compatibility] </i>
173 * @compatibility This method has compatibility issues with OSP compatible applications. @n
174 * For more information, see @ref CompIoPathPage "here".
178 * @privilege %http://tizen.org/privilege/audiorecorder
180 * @return An error code
181 * @param[in] destMediaPath The file destination to write @n
182 * The available paths start with prefixes retrieved from the functions such as: @n
183 * Tizen::App::App::GetInstance()->GetAppRootPath() @n
184 * Tizen::System::Environment::GetMediaPath() @n
185 * Tizen::System::Environment::GetExternalStoragePath()
186 * @param[in] overwrite Set to @c true to overwrite a file if it already exists, @n
188 * @exception E_SUCCESS The method is successful.
189 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
190 * @exception E_RESOURCE_UNAVAILABLE The required path is unavailable.
191 * @exception E_SYSTEM A system error has occurred.
192 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
193 * @exception E_STORAGE_FULL The storage is full.
194 * @exception E_OUT_OF_MEMORY The memory is insufficient.
195 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
196 * @remarks The application can register newly created files into the Contents database using Tizen::Content::ContentManager::CreateContent().
199 result CreateAudioFile(const Tizen::Base::String& destMediaPath, bool overwrite);
206 * @privilege %http://tizen.org/privilege/audiorecorder
208 * @return An error code
209 * @exception E_SUCCESS The method is successful.
210 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
211 * @exception E_SYSTEM A system error has occurred.
212 * @exception E_OUT_OF_MEMORY The memory is insufficient.
213 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
214 * @remarks This method is synchronous.
215 * @see CreateAudioFile()
220 * Records an audio file.
224 * @privilege %http://tizen.org/privilege/audiorecorder
226 * @return An error code
227 * @exception E_SUCCESS The method is successful.
228 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
229 * @exception E_SYSTEM A system error has occurred.
230 * @exception E_DEVICE_BUSY The recorder is under use by other application.
231 * @exception E_OUT_OF_MEMORY The memory is insufficient.
232 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
243 * @privilege %http://tizen.org/privilege/audiorecorder
245 * @return An error code
246 * @exception E_SUCCESS The method is successful.
247 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
248 * @exception E_SYSTEM A system error has occurred.
249 * @exception E_OUT_OF_MEMORY The memory is insufficient.
250 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
257 * Pauses a recording. @n
258 * To resume a recording after the %Pause() method is called, the Record() method must be called.
262 * @privilege %http://tizen.org/privilege/audiorecorder
264 * @return An error code
265 * @exception E_SUCCESS The method is successful.
266 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
267 * @exception E_SYSTEM A system error has occurred.
268 * @exception E_OUT_OF_MEMORY The memory is insufficient.
269 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
275 * Cancels a recording operation without saving the data.
279 * @privilege %http://tizen.org/privilege/audiorecorder
281 * @return An error code
282 * @exception E_SUCCESS The method is successful.
283 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
284 * @exception E_SYSTEM A system error has occurred.
285 * @exception E_OUT_OF_MEMORY The memory is insufficient.
286 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
287 * @remarks If this method is called, the state is changed to ::RECORDER_STATE_STOPPING. @n
288 * After IAudioRecorderEventListener::OnAudioRecorderCanceled() is called, the state is changed
289 * to @cRECORDER_STATE_STOPPED.
296 * Gets the state of an audio recorder.
300 * @return The current state of an audio recorder
306 RecorderState GetState(void) const;
309 * Gets the current recording time.
313 * @return The value indicating the current recording time in milliseconds, @n
314 * else @c -1 if the recording has not started as yet
316 long GetRecordingTime(void) const;
319 * Gets the current recording size.
323 * @return The value indicating the current recording size in bytes, @n
324 * else @c -1 if the recording has not started as yet
326 long GetRecordingSize(void) const;
329 * Sets the recording time limit for a file in milliseconds.
333 * @privilege %http://tizen.org/privilege/audiorecorder
335 * @return An error code
336 * @param[in] msTime The maximum recording time in milliseconds @n
337 * The time must be greater than @c 0.
338 * @exception E_SUCCESS The method is successful.
339 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
340 * @exception E_OUT_OF_RANGE The specified time is out of range.
341 * @exception E_OUT_OF_MEMORY The memory is insufficient.
342 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
343 * @remarks The default time is @c 60 seconds.
344 * @see GetMaxRecordingTime()
346 result SetMaxRecordingTime(long msTime);
349 * Gets the recording time limit of a file in milliseconds.
353 * @return A @c long value indicating the maximum recording time in milliseconds
354 * @see SetMaxRecordingTime()
356 long GetMaxRecordingTime(void) const;
360 * Sets the audio format of an audio recorder. @n
361 * Initially, the default format is set using the internal configuration.
363 * @brief <i> [Deprecated] </i>
364 * @deprecated This method is deprecated. Instead of this method, use the SetFormat(CodecType audioCodec, MediaContainerType container) method
365 * that sets the audio codec and container together.
368 * @privilege %http://tizen.org/privilege/audiorecorder
370 * @return An error code
371 * @param[in] format The audio format to set @n
372 * ::AUDIORECORDING_FORMAT_DEFAULT sets the system's default recording format.
373 * @exception E_SUCCESS The method is successful.
374 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
375 * @exception E_UNSUPPORTED_FORMAT The specified format is not supported.
376 * @exception E_OUT_OF_MEMORY The memory is insufficient.
377 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
381 result SetFormat(AudioRecordingFormat format);
385 * Gets the audio recording format of an audio recorder.
387 * @brief <i> [Deprecated] </i>
388 * @deprecated This method is deprecated. Instead of this method, use the GetFormat(CodecType& audioCodec,
389 * MediaContainerType& container) const method that gets the audio codec and container together.
392 * @return The audio recording format, @n
393 * else default format if SetFormat() is not called before calling this method
397 AudioRecordingFormat GetFormat(void) const;
400 * Sets the audio codec and the container of an audio recorder. @n
401 * Initially, the default codec and the container format are set using the internal configuration.
405 * @privilege %http://tizen.org/privilege/audiorecorder
407 * @return An error code
408 * @param[in] audioCodec The audio codec to set
409 * @param[in] container The media container to set
410 * @exception E_SUCCESS The method is successful.
411 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
412 * @exception E_UNSUPPORTED_CODEC The specified codec is not supported.
413 * @exception E_UNSUPPORTED_FORMAT The specified container format is not supported.
414 * @exception E_SYSTEM A system error has occurred.
415 * @exception E_OUT_OF_MEMORY The memory is insufficient.
416 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
417 * @remarks If the specified container does not support the specified codec, @c E_UNSUPPORTED_FORMAT may be returned.
418 * @see GetFormat( CodecType& audioCodec, MediaContainerType& container ) const
420 result SetFormat(CodecType audioCodec, MediaContainerType container);
423 * Gets the audio codec and container of an audio recorder.
427 * @return An error code
428 * @param[out] audioCodec The retrieved audio codec
429 * @param[out] container The retrieved container
430 * @exception E_SUCCESS The method is successful.
431 * @remarks If SetFormat(CodecType audioCodec, MediaContainerType container) is not called before calling
432 * this method, the default codec and container are retrieved. @n
433 * This method always returns E_SUCCESS.
434 * @see SetFormat( CodecType audioCodec, MediaContainerType container )
436 result GetFormat(CodecType& audioCodec, MediaContainerType& container) const;
439 * Gets a list of the supported audio codecs. @n
440 * Each list's item has a ::CodecType value.
444 * @return A list of supported audio codecs, @n
445 * else @c null if no codec is supported or if an exception occurs
446 * @exception E_SUCCESS The method is successful.
447 * @exception E_SYSTEM A system error has occurred.
448 * @exception E_OUT_OF_MEMORY The memory is insufficient.
449 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
450 * The return value must be released by the caller.
451 * @see SetFormat(CodecType audioCodec, MediaContainerType container)
452 * @see GetFormat(CodecType& audioCodec, MediaContainerType& container) const
454 Tizen::Base::Collection::IListT <CodecType>* GetSupportedCodecListN(void) const;
457 * Gets a list of the supported containers. @n
458 * Each list's item has a ::MediaContainerType value.
462 * @return A list of supported container list, @n
463 * else @c null if no container is supported or if an exception occurs
464 * @exception E_SUCCESS The method is successful.
465 * @exception E_SYSTEM A system error has occurred.
466 * @exception E_OUT_OF_MEMORY The memory is insufficient.
467 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
468 * The return value must be released by the caller.
469 * @see SetFormat(CodecType audioCodec, MediaContainerType container)
470 * @see GetFormat(CodecType& audioCodec, MediaContainerType& container) const
472 Tizen::Base::Collection::IListT <MediaContainerType>* GetSupportedContainerListN(void) const;
475 * Sets the audio recording quality of the audio recorder.
479 * @privilege %http://tizen.org/privilege/audiorecorder
481 * @return An error code
482 * @param[in] quality The audio recording quality of the audio recorder @n
483 * The default value is ::RECORDING_QUALITY_MEDIUM.
484 * @exception E_SUCCESS The method is successful.
485 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
486 * @exception E_INVALID_ARG The specified @c quality is not supported.
487 * @exception E_OUT_OF_MEMORY The memory is insufficient.
488 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
491 result SetQuality(RecordingQuality quality);
494 * Gets the audio recording quality of the audio recorder.
498 * @return The current audio recording quality of the audio recorder
501 RecordingQuality GetQuality(void) const;
504 * Sets the mute state of an audio recorder.
508 * @privilege %http://tizen.org/privilege/audiorecorder
510 * @return An error code
511 * @param[in] mute The mute state @n
512 * By default, the mute state is disabled.
513 * @exception E_SUCCESS The method is successful.
514 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
515 * @exception E_OUT_OF_MEMORY The memory is insufficient.
516 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
517 * @remarks The audio recording continues even though the audio recorder is in the mute state.
520 result SetMute(bool mute);
523 * Checks whether the mute state is enabled for an audio recorder.
527 * @return @c true if the audio recorder is not recording any sound, @n
531 bool IsMuted(void) const;
534 * Adds a stream filter to process the audio stream data while recording.
538 * @privilege %http://tizen.org/privilege/audiorecorder
540 * @return An error code
541 * @param[in] filter An instance of IAudioStreamFilter
542 * @exception E_SUCCESS The method is successful.
543 * @exception E_OBJ_ALREADY_EXIST The filter already exists.
544 * @exception E_OUT_OF_MEMORY The memory is insufficient.
545 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
546 * @remarks IAudioStreamFilter::ProcessAudioStream() is called when the audio frame is ready.
548 result AddAudioStreamFilter(IAudioStreamFilter& filter);
551 * Removes a stream filter to stop processing the audio stream data.
555 * @privilege %http://tizen.org/privilege/audiorecorder
557 * @return An error code
558 * @param[in] filter An instance of IAudioStreamFilter
559 * @exception E_SUCCESS The method is successful.
560 * @exception E_OBJ_NOT_FOUND The filter is not found.
561 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
563 result RemoveAudioStreamFilter(IAudioStreamFilter& filter);
567 * This is the copy constructor for this class.
571 * @remarks The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
574 AudioRecorder(const AudioRecorder&);
576 * This is the copy assignment operator for this class.
580 * @remarks The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
583 AudioRecorder& operator =(const AudioRecorder& audioRecorder);
585 friend class _AudioRecorderImpl;
586 _AudioRecorderImpl* __pImpl;