1 /*

     2 * Copyright (c) 2010 Ixonos Plc.

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - Initial contribution

    11 *

    12 * Contributors:

    13 * Ixonos Plc

    14 *

    15 * Description:  

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 #ifndef __AUDSONG_H__

    23 #define __AUDSONG_H__

    24 

    25 

    26 #include <e32base.h>

    27 #include <f32file.h>

    28 #include <e32std.h>

    29 

    30 #include "AudCommon.h"

    31 #include "AudObservers.h"

    32 

    33 

    34 // define _WRITE_OUTPUT_TO_FILE_ if you want audio engine to write its output to a file

    35 //#define _WRITE_OUTPUT_TO_FILE_;

    36 

    37 

    38 /*

    39 *    Forward declarations.

    40 */

    41 

    42 

    43 class MAudVisualizationObserver;

    44 class MAudSongProcessingObserver;

    45 class CAudSongProcessOperation;

    46 class CAudSongVisualizationOperation;

    47 class MAudSongObserver;

    48 class CAudClipInfo;

    49 class MAudClipInfoObserver;

    50 class CAudSongAddClipOperation;

    51 class CAudProcessor;

    52 

    53 // constants that represent special parameter values

    54 

    55 // clip end time (used when setting cutOut-times)

    56 const TInt KClipEndTime = -1;

    57 

    58 // KAllTrackIndices represents all tracks in ClipCount()-function

    59 const TInt KAllTrackIndices = -1;

    60 

    61 // Let audio engine to decide the bitrate

    62 const TInt KAudBitRateDefault = -1;

    63 

    64 

    65 /**

    66 * Audio song, which consists of zero or more audio clips

    67 *

    68 * @see  CAudClip

    69 */

    70 class CAudSong : public CBase

    71     {

    72 public:

    73     /* Constructors. */

    74     

    75     /**

    76     * Constructs a new empty CAudSong object. May leave if no resources are available.

    77     * 

    78     * Possible leave codes:

    79     *    - <code>KErrNoMemory</code> if memory allocation fails

    80     *

    81     * @param aFs  file server session to use to lock the audio

    82     *             clip files of the new song; or NULL to not to lock the files

    83     * @return  pointer to a new CAudSong instance

    84     */

    85     IMPORT_C static CAudSong* NewL(RFs *aFs);

    86     

    87     /**

    88     * Constructs a new empty CAudSong object and leaves the object in the cleanup stack.

    89     * 

    90     * Possible leave codes:

    91     *    - <code>KErrNoMemory</code> if memory allocation fails

    92     * 

    93     * @param aFs  file server session to use to lock the audio

    94     *             clip files of the new song; or NULL to not to lock the files

    95     * @return  pointer to a new CAudSong instance

    96     */

    97     IMPORT_C static CAudSong* NewLC(RFs *aFs);

    98     

    99     /**

   100     * Destroys the object and releases all resources.

   101     */

   102     IMPORT_C virtual ~CAudSong();

   103     

   104     

   105     /* Property methods. */

   106     

   107     /**

   108     * Returns an estimate of the total size of this song.

   109     * 

   110     * @return  size estimate in bytes

   111     */

   112     IMPORT_C TInt GetSizeEstimateL() const;

   113     

   114     /**

   115     * Returns an estimate of the size of this song between the given time interval.

   116     * 

   117     * @param aStartTime Beginning of the time interval

   118     * @param aEndTime End of the time interval

   119     * @return size estimate in bytes

   120     */

   121     IMPORT_C TInt GetFrameSizeEstimateL(TTimeIntervalMicroSeconds aStartTime, 

   122                                         TTimeIntervalMicroSeconds aEndTime) const;

   123     

   124     /**

   125     * Returns the properties of this song.

   126     * 

   127     * @return  output file properties

   128     */

   129     IMPORT_C TAudFileProperties OutputFileProperties() const;

   130     

   131     /**

   132     *

   133     * Generates decoder specific info needed for MP4

   134     * Caller is responsible for releasing aDecSpecInfo in the case ETrue is returned

   135     *

   136     * @param aMaxSize    maximum aDecSpecInfo size allowed    

   137     *

   138     */

   139     IMPORT_C TBool GetMP4DecoderSpecificInfoLC(HBufC8*& aDecSpecInfo, TInt aMaxSize) const;

   140 

   141     /**

   142     * Get processing time estimate based on trial. Asynchronous version, requires observer.

   143     *

   144     */

   145     IMPORT_C TBool GetTimeEstimateL(MAudTimeEstimateObserver& aObserver,

   146                                     TAudType aAudType,

   147                                     TInt aSamplingRate,

   148                                     TChannelMode aChannelMode,

   149                                     TInt aBitRate = -1);

   150                                     

   151     /**

   152     * Get processing time estimate based on hardcoded constants. Synchronous version.

   153     *

   154     * @return   estimated processing time for the song

   155     */

   156     IMPORT_C TTimeIntervalMicroSeconds GetTimeEstimateL();

   157     

   158     /**

   159     * Get the frame duration in microseconds. 

   160     *

   161     * @return   frame duration in microseconds

   162     */

   163     IMPORT_C TInt GetFrameDurationMicro();

   164 

   165 

   166     /* Audio clip management methods. */

   167     

   168     /**

   169     * Returns the number of audio clips in this song on a certain track.

   170     *

   171     * @param   aTrackIndex track index

   172     *

   173     * @return  number of audio clips on a defined track

   174     */

   175     IMPORT_C TInt ClipCount(TInt aTrackIndex = 0) const;

   176     

   177     /** 

   178     * Returns the audio clip at the specified index. 

   179     * Panics with code <code>EAudioClipIllegalIndex</code> if the clip index is invalid.

   180     *

   181     * @param aIndex            index of the clip on the certain track

   182     * @param aTrackIndex    index of the track

   183     *

   184     * @return  clip at the specified index.

   185     */    

   186     IMPORT_C CAudClip* Clip(TInt aIndex, TInt aTrackIndex = 0) const;

   187     

   188     /** 

   189     * Adds the specified audio clip to this song. Asynchronous operation

   190     * CAudSongObserver::NotifyClipAdded or CAudSongObserver::NotifyClipAddingFailed

   191     * is called once the operation has completed.

   192     *

   193     * Possible leave codes:

   194     *    - <code>KErrNoMemory</code> if memory allocation fails

   195     *    - <code>KErrNotSupported</code> if audio format is not supported

   196     *

   197     * @param aFileName   file name of the clip to add

   198     * @param aStartTime  start time of the clip in song timebase

   199     * @param aTrackIndex track index. Used to categorize clips.

   200     */

   201     IMPORT_C void AddClipL(const TDesC& aFileName,

   202         TTimeIntervalMicroSeconds aStartTime, TInt aTrackIndex = 0,

   203         TTimeIntervalMicroSeconds aCutInTime = TTimeIntervalMicroSeconds(0),

   204         TTimeIntervalMicroSeconds aCutOutTime = TTimeIntervalMicroSeconds(KClipEndTime));

   205     

   206     

   207     /** 

   208     * Removes the audio clip at the specified index from this song.

   209     * Panics with code <code>USER-130</code> if the clip index is invalid.

   210     *

   211     * @param aIndex  index of the clip to be removed

   212     * @param aTrackIndex track index

   213     */

   214     IMPORT_C void RemoveClip(TInt aIndex, TInt aTrackIndex = 0);

   215     

   216     /** 

   217     * Removes all audio clips and clears all effects

   218     *

   219     * @param aNotify ETrue if observer should be notified

   220     */

   221     IMPORT_C void Reset(TBool aNotify);

   222 

   223     /**

   224     *

   225     * Sets the duration of the output clip

   226     * If necessary, silence is generated in the end

   227     *

   228     * @param    aDuration    output clip length in microseconds

   229     * 

   230     * @return    ETrue if a new duration was set, EFalse otherwise

   231     *

   232     */

   233     IMPORT_C TBool SetDuration(TTimeIntervalMicroSeconds aDuration);

   234 

   235     

   236     /* Processing methods. */

   237     

   238     

   239     /**

   240     * Removes a dynamic level mark in a song. 

   241     * Panics with code <code>EAudioClipIllegalIndex</code> 

   242     * if the clip index is invalid.

   243     *

   244     * @param    aIndex index of the removed mark in this song

   245     * @return  ETrue if mark was removed, EFalse otherwise

   246     */

   247     IMPORT_C TBool RemoveDynamicLevelMark(TInt aIndex);

   248     

   249     

   250     /**

   251     * Sets an output file format

   252     *

   253     * NOTE: only the following combinations are allowed: 

   254     * AMR: single channel, 8000 Hz, 12000 kbps

   255     *

   256     * AAC/16kHz mono/stereo 

   257     * AAC/48kHz mono/stereo

   258     *

   259     * @return   ETrue if format was successfully changed, 

   260     *             EFalse if format cannot be set

   261     */

   262     IMPORT_C TBool SetOutputFileFormat(TAudType aAudType,

   263                                         TInt aSamplingRate,

   264                                         TChannelMode aChannelMode,

   265                                         TInt aBitRate = KAudBitRateDefault);

   266     

   267     /**

   268     * Checks if given properties are supported

   269     *

   270     *

   271     * @param    aProperties audio properties

   272     * @return   ETrue if properties are supported

   273     *           EFalse if not

   274     */

   275     IMPORT_C TBool AreOutputPropertiesSupported(const TAudFileProperties& aProperties );

   276     

   277     

   278     /*

   279     * Processing methods

   280     */

   281 

   282     /**

   283     * Starts a synchronous audio processing operation. After calling this function

   284     * the current song can be processed frame by frame by calling ProcessPieceL-function

   285     * Panics with 

   286     * <code>TAudPanic::ESongEmpty</code> if there are no clips 

   287     * in the song.

   288     *     

   289     */

   290     IMPORT_C TBool SyncStartProcessingL();

   291     

   292     /**

   293     * Processes synchronously next audio frame and passes it to the caller. 

   294     * If a processing operation has not been started, panic 

   295     * <code>TAudPanic::ESongProcessingNotRunning</code> is raised.

   296     *

   297     * Possibly leave codes:

   298     *    - <code>KErrNoMemory</code> if memory allocation fails

   299     *

   300     * NOTE: This function allocates memory and the caller is responsible for

   301     * releasing it.

   302     *

   303     * @param aFrame        pointer to a processed audio frame. Has to be deleted

   304     *                    when not needed anymore.

   305     * @param aDuration    Duration of processed audio frame in microseconds 

   306     *                    after decoding

   307     * 

   308     * @return ETrue        Processing operation completed, no more frames to be processed. 

   309     *                    No memory allocated.

   310     *          EFalse    Processing operation not completed. Last processed frame stored

   311     *                    in <code>aFrame</code>. Memory allocated for the processed frame

   312     *                      

   313     */

   314     IMPORT_C TBool SyncProcessFrameL(HBufC8*& aFrame, TInt& aProgress, 

   315                                 TTimeIntervalMicroSeconds& aDuration);

   316 

   317 

   318     /**

   319     * Cancels the processing operation. Used for only synchronous processing 

   320     * operations. If an operation is not running, 

   321     * panic <code>TAudPanic::ESongProcessingNotRunning</code> is raised

   322     */

   323     IMPORT_C void SyncCancelProcess();

   324 

   325 

   326     /* Observer methods. */

   327 

   328     /**

   329      * Registers a song observer. Panics with panic code 

   330      * <code>ESongObserverAlreadyRegistered</code> if the song observer is 

   331      * already registered.

   332      *

   333      * @param aObserver  observer that will receive the events

   334      */

   335     IMPORT_C void RegisterSongObserverL(MAudSongObserver* aObserver);

   336 

   337     /**

   338      * Unregisters a song observer. Panics with panic code 

   339      * <code>ESongObserverNotRegistered</code> if the song observer is not registered.

   340      *

   341      * @param aObserver  observer to be unregistered

   342      */

   343     IMPORT_C void UnregisterSongObserver(MAudSongObserver* aObserver);

   344     

   345     

   346     /** 

   347     * Adds the specified audio clip to this song. Asynchronous operation

   348     * CAudSongObserver::NotifyClipAdded or CAudSongObserver::NotifyClipAddingFailed

   349     * is called once the operation has completed.

   350     *

   351     * Possible leave codes:

   352     *    - <code>KErrNoMemory</code> if memory allocation fails

   353     *    - <code>KErrNotSupported</code> if audio format is not supported

   354     *

   355     * @param aFileHandle file handle of the clip to add

   356     * @param aStartTime  start time of the clip in song timebase

   357     * @param aTrackIndex track index. Used to categorize clips.

   358     */

   359     IMPORT_C void AddClipL(RFile* aFileHandle,

   360         TTimeIntervalMicroSeconds aStartTime, TInt aTrackIndex = 0,

   361         TTimeIntervalMicroSeconds aCutInTime = TTimeIntervalMicroSeconds(0),

   362         TTimeIntervalMicroSeconds aCutOutTime = TTimeIntervalMicroSeconds(KClipEndTime));

   363 

   364 

   365 private:

   366 

   367 

   368     // C++ constructor

   369     CAudSong(RFs *aFs);

   370 

   371     // functions for keeping clip indexes and arrays up to date

   372     void UpdateClipIndexes();

   373     void UpdateClipArray();

   374 

   375     /**

   376     * Returns a track domain clip index

   377     * of the clip whose song doman index is <code>aIndex</code>

   378     */

   379     TInt Index2IndexOnTrack(TInt aIndex);

   380 

   381     /*

   382     * Returns a song domain clip index

   383     */

   384     TInt FindClipIndexOnSong(const CAudClip* aClip) const;

   385     

   386     /*

   387     * ConstructL

   388     */

   389     

   390     void ConstructL();

   391 

   392 private:

   393     

   394     // Member variables

   395     

   396     // File server session.

   397     RFs* iFs;

   398     // Audio clip array.

   399     RPointerArray<CAudClip> iClipArray;

   400     

   401     // Marks used for manual level controlling

   402     RPointerArray<TAudDynamicLevelMark> iDynamicLevelMarkArray;

   403     

   404     // Properties of the output file.

   405     TAudFileProperties* iProperties;

   406     

   407     // Duration of the song

   408     // if iSongDuration is greater than the cut out time of the last output clip,

   409     // silence is generated in the end

   410     TTimeIntervalMicroSeconds iSongDuration;

   411     

   412     // a flag to indicate whether the user has set the duration manually

   413     // if not, the duration is the cutOutTime of the last input clip

   414     TBool iSongDurationManuallySet;

   415 

   416     // Observer array of the song class.

   417     RPointerArray<MAudSongObserver> iObserverArray;

   418     

   419     // Normalizing of this audio clip.

   420     // If ETrue, the song as a whole is to be normalized

   421     TBool iNormalize;

   422     

   423     // process operation owned by this

   424     CAudSongProcessOperation* iProcessOperation;

   425     

   426     // clip adding operation owned by this

   427     CAudSongAddClipOperation* iAddOperation;

   428     

   429     // song visualization operation owned by this

   430     CAudSongVisualizationOperation* iVisualizationOperation;

   431     

   432     

   433 private:

   434 

   435     // Notifications to fire callbacks to all registered listeners -------->

   436     

   437     void FireClipAdded(CAudSong* aSong, CAudClip* aClip, TInt aIndex, TInt aTrackIndex);

   438     

   439     void FireClipAddingFailed(CAudSong* aSong, TInt aError, TInt aTrackIndex);

   440 

   441     void FireClipRemoved(CAudSong* aSong, TInt aIndex, TInt aTrackIndex);

   442 

   443     void FireClipIndicesChanged(CAudSong* aSong, TInt aOldIndex, 

   444                                      TInt aNewIndex, TInt aTrackIndex);

   445 

   446     void FireClipTimingsChanged(CAudSong* aSong, CAudClip* aClip);

   447 

   448     void FireDynamicLevelMarkInserted(CAudSong& aSong, 

   449         TAudDynamicLevelMark& aMark, 

   450         TInt aIndex);

   451     

   452     void FireDynamicLevelMarkInserted(CAudClip& aClip, 

   453         TAudDynamicLevelMark& aMark, 

   454         TInt aIndex);

   455 

   456     void FireDynamicLevelMarkRemoved(CAudSong& aSong, TInt aIndex);

   457     void FireDynamicLevelMarkRemoved(CAudClip& aClip, TInt aIndex);

   458     void FireSongReseted(CAudSong& aSong);

   459     void FireClipReseted(CAudClip& aClip);

   460 

   461     // <------------ Notifications to fire callbacks to all registered listeners

   462 

   463     friend class CAudSongAddClipOperation;

   464     friend class CAudClip;

   465     friend class CAudProcessorImpl;

   466     

   467     

   468 #ifdef _WRITE_OUTPUT_TO_FILE_

   469 

   470     TBool iFileOpen;

   471     RFs iDebFs;

   472     RFile iAudioFile;

   473     RFile iTextFile;

   474     

   475     

   476 #endif

   477     

   478     };

   479 

   480 

   481 // Abstract interface class to get events from audio processor

   482 

   483 class MProcProcessObserver 

   484     {

   485 

   486 public:

   487     /**

   488      * Called to notify that a new audio processing operation has been started. 

   489      *

   490      */

   491     virtual void NotifyAudioProcessingStartedL() = 0;

   492 

   493     /**

   494      * Called to inform about the current progress of the audio processing operation.

   495      *

   496      * @param aPercentage  percentage of the operation completed, must be 

   497        *                     in range 0..100

   498      */

   499     virtual void NotifyAudioProcessingProgressed(TInt aPercentage) = 0;

   500 

   501     /**

   502     * Called to notify that the song processing operation has been completed. 

   503     * 

   504     * @param aError  error code why the operation was completed. 

   505     *                <code>KErrNone</code> if the operation was completed 

   506     *                successfully.

   507     */

   508     virtual void NotifyAudioProcessingCompleted(TInt aError) = 0;

   509 

   510     };

   511 

   512 

   513 

   514 /**

   515 * Internal class for processing a song.

   516 */

   517 class CAudSongProcessOperation : public CBase, public MProcProcessObserver, public MAudTimeEstimateObserver

   518     {

   519     

   520     

   521     

   522 public:

   523 

   524     

   525     static CAudSongProcessOperation* NewL(CAudSong* aSong);

   526 

   527     // From MProcProcessObserver

   528 

   529     void NotifyAudioProcessingStartedL();

   530     void NotifyAudioProcessingProgressed(TInt aPercentage);

   531     void NotifyAudioProcessingCompleted(TInt aError);

   532     

   533     // From // MAudTimeEstimateObserver

   534     void NotifyTimeEstimateReady(TInt64 aTimeEstimate);

   535 

   536     /**

   537     * Starts asyncronous processing a song

   538     * 

   539     * Can leave with one of the system wide error codes

   540     *

   541     * Possible panic code

   542     * <code>ESongProcessingOperationAlreadyRunning</code>

   543     *

   544     * @param    aFileName    output file name

   545     * @param    aObserver    an observer to be notified of progress

   546     * @param    aPriority    priority of audio processing operation

   547     */

   548     void StartASyncProcL(const TDesC& aFileName, 

   549         MAudSongProcessingObserver& aObserver, TInt aPriority);

   550 

   551 

   552     /**

   553     * Starts syncronous song processing

   554     * 

   555     * Can leave with one of the system wide error codes

   556     *

   557     * Possible panic code

   558     * <code>ESongProcessingOperationAlreadyRunning</code>

   559     *

   560     */

   561     TBool StartSyncProcL();

   562     

   563     

   564     /**

   565     * Processes synchronously next audio frame and passes it to the caller. 

   566     * If a processing operation has not been started, panic 

   567     * <code>TAudPanic::ESongProcessingNotRunning</code> is raised.

   568     *

   569     * Possibly leave codes:

   570     *    - <code>KErrNoMemory</code> if memory allocation fails

   571     *

   572     * NOTE: This function allocates memory and the caller is responsible for

   573     * releasing it.

   574     *

   575     * @param aFrame        pointer to a processed audio frame. Has to be deleted

   576     *                    when not needed anymore.

   577     * @param aDuration    Duration of processed audio frame in microseconds 

   578     *                    after decoding

   579     * 

   580     * @return ETrue        Processing operation completed, no more frames to be processed. 

   581     *                    No memory allocated.

   582     *          EFalse    Processing operation not completed. Last processed frame stored

   583     *                    in <code>aFrame</code>. Memory allocated for the processed frame

   584     *                      

   585     */

   586     TBool ProcessSyncPieceL(HBufC8*& aFrame, TInt& aProgress,

   587                                        TTimeIntervalMicroSeconds& aDuration);

   588 

   589     /**

   590     * Cancels both syncronous and and asyncronous song processing operation and deletes the output file

   591     *

   592     * Possible panic code

   593     * <code>ESongProcessingOperationNotRunning</code>

   594     *

   595     */

   596     void Cancel();

   597     

   598     TBool GetTimeEstimateL(MAudTimeEstimateObserver& aTEObserver);

   599 

   600 

   601 private:

   602 

   603     CAudSongProcessOperation(CAudSong* aSong);

   604     void ConstructL();

   605     virtual ~CAudSongProcessOperation();

   606     

   607 private:

   608     

   609    /* 

   610     * Member Variables

   611     */

   612     

   613     // song

   614     CAudSong *iSong;

   615     

   616     // song processing observer

   617     MAudSongProcessingObserver* iObserver;

   618     

   619     // time estimate observer

   620     MAudTimeEstimateObserver* iTEObserver;

   621     

   622     // A flag that indicates whether this song has changed since

   623     // the last processing

   624     TBool iChanged;

   625     

   626     // processor owned by this

   627     CAudProcessor* iProcessor;

   628     

   629     friend class CAudSong;

   630     

   631     

   632     };

   633 

   634 

   635 /**

   636 * Internal class for adding clips.

   637 */

   638 class CAudSongAddClipOperation : public CBase, public MAudClipInfoObserver 

   639     {

   640 

   641 public:

   642 

   643     /*

   644     * Constuctor & destructor

   645     */

   646 

   647     static CAudSongAddClipOperation* NewL(CAudSong* aSong);

   648 

   649     virtual ~CAudSongAddClipOperation();

   650         

   651     /*

   652     * From base class MAudClipInfoObserver

   653     */

   654     virtual void NotifyClipInfoReady(CAudClipInfo& aInfo, 

   655         TInt aError);

   656     

   657     

   658 private:

   659     

   660     /*

   661     * ConstructL

   662     */

   663     void ConstructL();

   664     

   665     /*

   666     * C++ constructor

   667     */

   668     CAudSongAddClipOperation(CAudSong* aSong);

   669     

   670     /*

   671     * Completes add clip operation

   672     */

   673     void CompleteAddClipOperation();

   674  

   675     

   676 private:

   677 

   678     // song

   679     CAudSong* iSong;

   680     

   681     // clip that we are trying to add

   682     CAudClip* iClip;

   683     

   684     // error possible caught by callback function NotifyClipInfoReady

   685     TInt iError;

   686     

   687     friend class CAudSong;

   688     };

   689 

   690 

   691 

   692 #endif