inc/FMediaAudioRecorder.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file                FMediaAudioRecorder.h
  20  * @brief                This is the header file for the %AudioRecorder class.
  21  *
  22  * This header file contains the declarations of the %AudioRecorder class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_RECORDER_H_
  26 #define _FMEDIA_AUDIO_RECORDER_H_
  27
  28 #include <FMediaAudioRecorderTypes.h>
  29 #include <FMediaIAudioRecorderEventListener.h>
  30 #include <FMediaTypes.h>
  31
  32 namespace Tizen { namespace Media
  33 {
  34
  35 class _AudioRecorderImpl;
  36 class IAudioStreamFilter;
  37
  38 /**
  39  * @class       AudioRecorder
  40  * @brief       This class records the audio data into a file.
  41  *
  42  * @since               2.0
  43  *
  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.
  48  *
  49  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/recording_audio.htm">Recording Audio</a>.
  50  *
  51  * The following example demonstrates how to use the %AudioRecorder class.
  52  *
  53  *
  54  * @code
  55  * #include <FBase.h>
  56  * #include <FIo.h>
  57  * #include <FApp.h>
  58  * #include <FMedia.h>
  59  *
  60  * using namespace Tizen::Base;
  61  * using namespace Tizen::Io;
  62  * using namespace Tizen::Media;
  63  *
  64  * class AudioRecorderSample
  65  *     : public IAudioRecorderEventListener
  66  * {
  67  * public:
  68  *     result Start(void);
  69  *     void Stop(void);
  70  *
  71  * protected:
  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) {}
  79  *
  80  * private:
  81  *     AudioRecorder __recorder;
  82  * };
  83  *
  84  * result
  85  * AudioRecorderSample::Start(void)
  86  * {
  87  *     result r;
  88  *     String destFilePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.amr";
  89  *
  90  *     r = __recorder.Construct(*this);
  91  *     if (IsFailed(r))
  92  *     {
  93  *         return r;
  94  *     }
  95  *
  96  *     r = __recorder.CreateAudioFile(destFilePath, true);
  97  *     if (IsFailed(r))
  98  *     {
  99  *         return r;
 100  *     }
 101  *
 102  *     r = __recorder.Record();
 103  *     if (IsFailed(r))
 104  *     {
 105  *         return r;
 106  *     }
 107  *
 108  *     return E_SUCCESS;
 109  * }
 110  *
 111  * void
 112  * AudioRecorderSample::Stop(void)
 113  * {
 114  *     __recorder.Stop();
 115  *     __recorder.Close();
 116  * }
 117  *
 118  * @endcode
 119  *
 120  */
 121
 122 class _OSP_EXPORT_ AudioRecorder
 123         : public Tizen::Base::Object
 124 {
 125
 126 public:
 127         /**
 128          * This is the default constructor for this class.
 129          *
 130          * @since               2.0
 131          *
 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.
 134          */
 135         AudioRecorder(void);
 136
 137         /**
 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.
 142          *
 143          * @since               2.0
 144          *
 145          */
 146         virtual ~AudioRecorder(void);
 147
 148
 149 public:
 150         /**
 151         * Initializes this instance of %AudioRecorder with the specified listener.
 152         *
 153         * @since                2.0
 154         *
 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.
 162         */
 163         result Construct(IAudioRecorderEventListener& listener);
 164
 165         /**
 166         * Creates an audio file for the recording.
 167         *
 168         * @if OSPCOMPAT
 169         * @brief <i> [Compatibility] </i>
 170         * @endif
 171         * @since                2.0
 172         * @if OSPCOMPAT
 173         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 174         *                                       For more information, see @ref CompIoPathPage "here".
 175         * @endif
 176         *
 177         * @privlevel        public
 178         * @privilege    %http://tizen.org/privilege/audiorecorder
 179         *
 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
 187         *                                                                               else @c false
 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().
 197         * @see Close()
 198         */
 199         result CreateAudioFile(const Tizen::Base::String& destMediaPath, bool overwrite);
 200
 201         /**
 202         * Closes a file.
 203         *
 204         * @since                2.0
 205         * @privlevel        public
 206         * @privilege    %http://tizen.org/privilege/audiorecorder
 207         *
 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()
 216         */
 217         result Close(void);
 218
 219         /**
 220         * Records an audio file.
 221         *
 222         * @since                2.0
 223         * @privlevel        public
 224         * @privilege    %http://tizen.org/privilege/audiorecorder
 225         *
 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.
 233         * @see                  Stop()
 234         * @see          Pause()
 235         */
 236         result Record(void);
 237
 238         /**
 239         * Stops a recording.
 240         *
 241         * @since                2.0
 242         * @privlevel        public
 243         * @privilege    %http://tizen.org/privilege/audiorecorder
 244         *
 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.
 251         * @see                  Record()
 252         * @see          Pause()
 253         */
 254         result Stop(void);
 255
 256         /**
 257         * Pauses a recording. @n
 258         * To resume a recording after the %Pause() method is called, the Record() method must be called.
 259         *
 260         * @since                2.0
 261         * @privlevel        public
 262         * @privilege    %http://tizen.org/privilege/audiorecorder
 263         *
 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.
 270         * @see          Stop()
 271         */
 272         result Pause(void);
 273
 274         /**
 275         * Cancels a recording operation without saving the data.
 276         *
 277         * @since                2.0
 278         * @privlevel        public
 279         * @privilege    %http://tizen.org/privilege/audiorecorder
 280         *
 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.
 290         * @see          Record()
 291         * @see      Stop()
 292         */
 293         result Cancel(void);
 294
 295         /**
 296         * Gets the state of an audio recorder.
 297         *
 298         * @since                2.0
 299         *
 300         * @return           The current state of an audio recorder
 301         * @see              Close()
 302         * @see          Record()
 303         * @see          Stop()
 304         * @see          Pause()
 305         */
 306         RecorderState GetState(void) const;
 307
 308         /**
 309         * Gets the current recording time.
 310         *
 311         * @since                2.0
 312         *
 313         * @return           The value indicating the current recording time in milliseconds, @n
 314         *                               else @c -1 if the recording has not started as yet
 315         */
 316         long GetRecordingTime(void) const;
 317
 318         /**
 319         * Gets the current recording size.
 320         *
 321         * @since                2.0
 322         *
 323         * @return               The value indicating the current recording size in bytes, @n
 324         *                               else @c -1 if the recording has not started as yet
 325         */
 326         long GetRecordingSize(void) const;
 327
 328         /**
 329         * Sets the recording time limit for a file in milliseconds.
 330         *
 331         * @since                2.0
 332         * @privlevel        public
 333         * @privilege    %http://tizen.org/privilege/audiorecorder
 334         *
 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()
 345         */
 346         result SetMaxRecordingTime(long msTime);
 347
 348         /**
 349         * Gets the recording time limit of a file in milliseconds.
 350         *
 351         * @since                2.0
 352         *
 353         * @return               A @c long value indicating the maximum recording time in milliseconds
 354         * @see                  SetMaxRecordingTime()
 355         */
 356         long GetMaxRecordingTime(void) const;
 357
 358         /**
 359         * @if OSPDEPREC
 360         * Sets the audio format of an audio recorder. @n
 361         * Initially, the default format is set using the internal configuration.
 362         *
 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.
 366         * @since                2.0
 367         * @privlevel        public
 368         * @privilege    %http://tizen.org/privilege/audiorecorder
 369         *
 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.
 378         * @see                  GetFormat()
 379         * @endif
 380         */
 381         result SetFormat(AudioRecordingFormat format);
 382
 383         /**
 384         * @if OSPDEPREC
 385         * Gets the audio recording format of an audio recorder.
 386         *
 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.
 390         * @since                2.0
 391         *
 392         * @return               The audio recording format, @n
 393         *               else default format if SetFormat() is not called before calling this method
 394         * @see                  SetFormat()
 395         * @endif
 396         */
 397         AudioRecordingFormat GetFormat(void) const;
 398
 399         /**
 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.
 402         *
 403         * @since                2.0
 404         * @privlevel        public
 405         * @privilege    %http://tizen.org/privilege/audiorecorder
 406         *
 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
 419         */
 420         result SetFormat(CodecType audioCodec, MediaContainerType container);
 421
 422         /**
 423         * Gets the audio codec and container of an audio recorder.
 424         *
 425         * @since                2.0
 426         *
 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 )
 435         */
 436         result GetFormat(CodecType& audioCodec, MediaContainerType& container) const;
 437
 438         /**
 439         * Gets a list of the supported audio codecs. @n
 440         * Each list's item has a ::CodecType value.
 441         *
 442         * @since                2.0
 443         *
 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
 453         */
 454         Tizen::Base::Collection::IListT <CodecType>* GetSupportedCodecListN(void) const;
 455
 456         /**
 457         * Gets a list of the supported containers. @n
 458         * Each list's item has a ::MediaContainerType value.
 459         *
 460         * @since                2.0
 461         *
 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
 471         */
 472         Tizen::Base::Collection::IListT <MediaContainerType>* GetSupportedContainerListN(void) const;
 473
 474         /**
 475         * Sets the audio recording quality of the audio recorder.
 476         *
 477         * @since                2.0
 478         * @privlevel        public
 479         * @privilege    %http://tizen.org/privilege/audiorecorder
 480         *
 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.
 489         * @see                  GetQuality()
 490         */
 491         result SetQuality(RecordingQuality quality);
 492
 493         /**
 494         * Gets the audio recording quality of the audio recorder.
 495         *
 496         * @since                2.0
 497         *
 498         * @return               The current audio recording quality of the audio recorder
 499         * @see                  SetQuality()
 500         */
 501         RecordingQuality GetQuality(void) const;
 502
 503         /**
 504         * Sets the mute state of an audio recorder.
 505         *
 506         * @since                2.0
 507         * @privlevel        public
 508         * @privilege    %http://tizen.org/privilege/audiorecorder
 509         *
 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.
 518         * @see                  IsMuted()
 519         */
 520         result SetMute(bool mute);
 521
 522         /**
 523         * Checks whether the mute state is enabled for an audio recorder.
 524         *
 525         * @since                2.0
 526         *
 527         * @return               @c true if the audio recorder is not recording any sound, @n
 528         *                               else @c false
 529         * @see                  SetMute()
 530         */
 531         bool IsMuted(void) const;
 532
 533         /**
 534         * Adds a stream filter to process the audio stream data while recording.
 535         *
 536         * @since                2.1
 537         * @privlevel    public
 538         * @privilege    %http://tizen.org/privilege/audiorecorder
 539         *
 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.
 547         */
 548         result AddAudioStreamFilter(IAudioStreamFilter& filter);
 549
 550         /**
 551         * Removes a stream filter to stop processing the audio stream data.
 552         *
 553         * @since                2.1
 554         * @privlevel    public
 555         * @privilege    %http://tizen.org/privilege/audiorecorder
 556         *
 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.
 562         */
 563         result RemoveAudioStreamFilter(IAudioStreamFilter& filter);
 564
 565 private:
 566         /**
 567          * This is the copy constructor for this class.
 568          *
 569          * @since               2.0
 570          *
 571          * @remarks         The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 572          * @see                 Construct()
 573          */
 574         AudioRecorder(const AudioRecorder&);
 575         /**
 576          * This is the copy assignment operator for this class.
 577          *
 578          * @since               2.0
 579          *
 580          * @remarks         The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 581          *
 582          */
 583         AudioRecorder& operator =(const AudioRecorder& audioRecorder);
 584
 585         friend class _AudioRecorderImpl;
 586         _AudioRecorderImpl* __pImpl;
 587
 588 };
 589
 590 }}// Tizen::Media
 591
 592 #endif