AudioIO.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  AudioIO.h
 
  Dominic Mazzoni
 
  Use the PortAudio library to play and record sound
 
**********************************************************************/
 
#ifndef __AUDACITY_AUDIO_IO__
#define __AUDACITY_AUDIO_IO__
 
#include "AudioIOBase.h" // to inherit
#include "PlaybackSchedule.h" // member variable
 
#include <functional>
#include <memory>
#include <mutex>
#include <thread>
#include <utility>
#include <wx/atomic.h> // member variable
 
#include "PluginProvider.h" // for PluginID
#include "Observer.h"
#include "SampleCount.h"
#include "SampleFormat.h"
 
class wxArrayString;
class AudioIOBase;
class AudioIO;
class RingBuffer;
class Mixer;
class RealtimeEffectState;
class Resample;
 
class AudacityProject;
 
class PlayableTrack;
using PlayableTrackConstArray =
   std::vector < std::shared_ptr < const PlayableTrack > >;
 
class Track;
class SampleTrack;
using SampleTrackArray = std::vector < std::shared_ptr < SampleTrack > >;
using SampleTrackConstArray = std::vector < std::shared_ptr < const SampleTrack > >;
 
class WritableSampleTrack;
using WritableSampleTrackArray =
   std::vector < std::shared_ptr < WritableSampleTrack > >;
 
struct PaStreamCallbackTimeInfo;
typedef unsigned long PaStreamCallbackFlags;
typedef int PaError;
 
namespace RealtimeEffects {
   class ProcessingScope;
}
 
bool ValidateDeviceNames();
 
enum class Acknowledge { eNone = 0, eStart, eStop };
 
struct AudioIOEvent {
   AudacityProject *pProject;
   enum Type {
      PLAYBACK,
      CAPTURE,
      MONITOR,
   } type;
   bool on;
};
 
struct AUDIO_IO_API TransportTracks final {
   TransportTracks() = default;
   TransportTracks(
      TrackList &trackList, bool selectedOnly,
      bool nonWaveToo = false 
   );
 
   SampleTrackConstArray playbackTracks;
   WritableSampleTrackArray captureTracks;
   PlayableTrackConstArray otherPlayableTracks;
 
   // This is a subset of playbackTracks
   SampleTrackConstArray prerollTracks;
};
 
int audacityAudioCallback(
   const void *inputBuffer, void *outputBuffer,
   unsigned long framesPerBuffer,
   const PaStreamCallbackTimeInfo *timeInfo,
   PaStreamCallbackFlags statusFlags, void *userData );
 
class AudioIOExt;
 
class AUDIO_IO_API AudioIoCallback /* not final */
   : public AudioIOBase
{
public:
   AudioIoCallback();
   ~AudioIoCallback();
 
public:
   // This function executes in a thread spawned by the PortAudio library
   int AudioCallback(
      constSamplePtr inputBuffer, float *outputBuffer,
      unsigned long framesPerBuffer,
      const PaStreamCallbackTimeInfo *timeInfo,
      const PaStreamCallbackFlags statusFlags, void *userData);
 
   class AUDIO_IO_API AudioIOExtIterator {
   public:
      using difference_type = ptrdiff_t;
      using value_type = AudioIOExt &;
      using pointer = AudioIOExt *;
      using reference = AudioIOExt &;
      using iterator_category = std::forward_iterator_tag;
 
      explicit AudioIOExtIterator( AudioIoCallback &audioIO, bool end )
         : mIterator{ end
            ? audioIO.mAudioIOExt.end()
            : audioIO.mAudioIOExt.begin() }
      {}
      AudioIOExtIterator &operator ++ () { ++mIterator; return *this; }
      auto operator *() const -> AudioIOExt &;
      friend inline bool operator == (
         const AudioIOExtIterator &xx, const AudioIOExtIterator &yy)
      {
         return xx.mIterator == yy.mIterator;
      }
      friend inline bool operator != (
         const AudioIOExtIterator &xx, const AudioIOExtIterator &yy)
      {
         return !(xx == yy);
      }
   private:
      std::vector<std::unique_ptr<AudioIOExtBase>>::const_iterator mIterator;
   };
   struct AudioIOExtRange {
      AudioIOExtIterator first;
      AudioIOExtIterator second;
      AudioIOExtIterator begin() const { return first; }
      AudioIOExtIterator end() const { return second; }
   };
 
   AudioIOExtRange Extensions() {
      return {
         AudioIOExtIterator{ *this, false },
         AudioIOExtIterator{ *this, true }
      };
   }
 
   std::shared_ptr< AudioIOListener > GetListener() const
      { return mListener.lock(); }
   void SetListener( const std::shared_ptr< AudioIOListener > &listener);
   
   // Part of the callback
   int CallbackDoSeek();
 
   // Part of the callback
   void CallbackCheckCompletion(
      int &callbackReturn, unsigned long len);
 
   int mbHasSoloTracks;
   int mCallbackReturn;
   // Helpers to determine if tracks have already been faded out.
   unsigned  CountSoloingTracks();
 
   using OldChannelGains = std::array<float, 2>;
   bool TrackShouldBeSilent( const SampleTrack &wt );
   bool TrackHasBeenFadedOut(
      const SampleTrack &wt, const OldChannelGains &gains);
   bool AllTracksAlreadySilent();
 
   void CheckSoundActivatedRecordingLevel(
      float *inputSamples,
      unsigned long framesPerBuffer
   );
 
   void AddToOutputChannel( unsigned int chan, // index into gains
      float * outputMeterFloats,
      float * outputFloats,
      const float * tempBuf,
      bool drop,
      unsigned long len,
      const SampleTrack *vt,
      OldChannelGains &gains
   );
   bool FillOutputBuffers(
      float *outputBuffer,
      unsigned long framesPerBuffer,
      float *outputMeterFloats
   );
   void DrainInputBuffers(
      constSamplePtr inputBuffer, 
      unsigned long framesPerBuffer,
      const PaStreamCallbackFlags statusFlags,
      float * tempFloats
   );
   void UpdateTimePosition(
      unsigned long framesPerBuffer
   );
   void DoPlaythrough(
      constSamplePtr inputBuffer, 
      float *outputBuffer,
      unsigned long framesPerBuffer,
      float *outputMeterFloats
   );
   void SendVuInputMeterData(
      const float *inputSamples,
      unsigned long framesPerBuffer
   );
   void SendVuOutputMeterData(
      const float *outputMeterFloats,
      unsigned long framesPerBuffer
   );
 
   size_t GetCommonlyReadyPlayback();
 
   size_t GetCommonlyWrittenForPlayback();
 
   long    mNumPauseFrames;
 
#ifdef EXPERIMENTAL_AUTOMATED_INPUT_LEVEL_ADJUSTMENT
   bool           mAILAActive;
   bool           mAILAClipped;
   int            mAILATotalAnalysis;
   int            mAILAAnalysisCounter;
   double         mAILAMax;
   double         mAILAGoalPoint;
   double         mAILAGoalDelta;
   double         mAILAAnalysisTime;
   double         mAILALastStartTime;
   double         mAILAChangeFactor;
   double         mAILATopLevel;
   double         mAILAAnalysisEndTime;
   double         mAILAAbsolutStartTime;
   unsigned short mAILALastChangeType;  //0 - no change, 1 - increase change, 2 - decrease change
#endif
 
   std::thread mAudioThread;
   std::atomic<bool> mFinishAudioThread{ false };
 
   ArrayOf<std::unique_ptr<Resample>> mResample;
   ArrayOf<std::unique_ptr<RingBuffer>> mCaptureBuffers;
   WritableSampleTrackArray      mCaptureTracks;
   ArrayOf<std::unique_ptr<RingBuffer>> mPlaybackBuffers;
   SampleTrackConstArray      mPlaybackTracks;
   // Old gain is used in playback in linearly interpolating
   // the gain.
   std::vector<OldChannelGains> mOldChannelGains;
   // Temporary buffers, each as large as the playback buffers
   std::vector<SampleBuffer> mScratchBuffers;
   std::vector<float *> mScratchPointers; 
 
   std::vector<std::unique_ptr<Mixer>> mPlaybackMixers;
 
   std::atomic<float>  mMixerOutputVol{ 1.0 };
   static int          mNextStreamToken;
   double              mFactor;
   unsigned long       mMaxFramesOutput; // The actual number of frames output.
   bool                mbMicroFades;
 
   double              mSeek;
   PlaybackPolicy::Duration mPlaybackRingBufferSecs;
   double              mCaptureRingBufferSecs;
 
   size_t              mPlaybackSamplesToCopy;
   size_t              mPlaybackQueueMinimum;
 
   double              mMinCaptureSecsToCopy;
   bool                mSoftwarePlaythrough;
 
   bool                mPauseRec;
   float               mSilenceLevel;
   unsigned int        mNumCaptureChannels;
   unsigned int        mNumPlaybackChannels;
   sampleFormat        mCaptureFormat;
   unsigned long long  mLostSamples{ 0 };
   std::atomic<bool>   mAudioThreadShouldCallTrackBufferExchangeOnce;
   std::atomic<bool>   mAudioThreadTrackBufferExchangeLoopRunning;
   std::atomic<bool>   mAudioThreadTrackBufferExchangeLoopActive;
      
   std::atomic<Acknowledge>  mAudioThreadAcknowledge;
 
   // Async start/stop + wait of AudioThread processing.
   // Provided to allow more flexibility, however use with caution:
   // never call Stop between Start and the wait for Started (and the converse)
   void StartAudioThread();
   void WaitForAudioThreadStarted();
   void StopAudioThread();
   void WaitForAudioThreadStopped();
 
   void ProcessOnceAndWait( std::chrono::milliseconds sleepTime = std::chrono::milliseconds(50) );
 
 
 
   std::atomic<bool>   mForceFadeOut{ false };
 
   wxLongLong          mLastPlaybackTimeMillis;
 
   double              mLastRecordingOffset;
   PaError             mLastPaError;
 
protected:
 
   float GetMixerOutputVol() {
      return mMixerOutputVol.load(std::memory_order_relaxed); }
   void SetMixerOutputVol(float value) {
      mMixerOutputVol.store(value, std::memory_order_relaxed); }
 
   std::weak_ptr< AudioIOListener > mListener;
 
   bool mUsingAlsa { false };
 
   // For cacheing supported sample rates
   static double mCachedBestRateOut;
   static bool mCachedBestRatePlaying;
   static bool mCachedBestRateCapturing;
 
   // Serialize main thread and PortAudio thread's attempts to pause and change
   // the state used by the third, Audio thread.
   wxMutex mSuspendAudioThread;
 
public:
   // Whether an exception (as for exhaustion of resource space) was detected
   // in recording, and not yet cleared at the end of the procedure to stop
   // recording.
   bool HasRecordingException() const
      { return mRecordingException; }
 
protected:
   // A flag tested and set in one thread, cleared in another.  Perhaps
   // this guarantee of atomicity is more cautious than necessary.
   wxAtomicInt mRecordingException {};
   void SetRecordingException()
      { wxAtomicInc( mRecordingException ); }
   void ClearRecordingException()
      { if (mRecordingException) wxAtomicDec( mRecordingException ); }
 
   std::vector< std::pair<double, double> > mLostCaptureIntervals;
   bool mDetectDropouts{ true };
 
public:
   // Pairs of starting time and duration
   const std::vector< std::pair<double, double> > &LostCaptureIntervals()
   { return mLostCaptureIntervals; }
 
   // Used only for testing purposes in alpha builds
   bool mSimulateRecordingErrors{ false };
 
   // Whether to check the error code passed to audacityAudioCallback to
   // detect more dropouts
   std::atomic<bool> mDetectUpstreamDropouts{ true };
 
protected:
   RecordingSchedule mRecordingSchedule{};
   PlaybackSchedule mPlaybackSchedule;
 
   struct TransportState;
   std::unique_ptr<TransportState> mpTransportState;
 
private:
   using AudioIOBase::mAudioIOExt;
};
 
struct PaStreamInfo;
 
class AUDIO_IO_API AudioIO final
   : public AudioIoCallback
   , public Observer::Publisher<AudioIOEvent>
{
 
   AudioIO();
   ~AudioIO();
   void StartThread();
 
public:
   // This might return null during application startup or shutdown
   static AudioIO *Get();
 
 
   std::shared_ptr<RealtimeEffectState>
   AddState(AudacityProject &project, Track *pTrack, const PluginID & id);
 
 
   std::shared_ptr<RealtimeEffectState>
   ReplaceState(AudacityProject &project,
      Track *pTrack, size_t index, const PluginID & id);
 
   void RemoveState(AudacityProject &project,
      Track *pTrack, std::shared_ptr<RealtimeEffectState> pState);
 
   void StartMonitoring( const AudioIOStartStreamOptions &options );
 
   int StartStream(const TransportTracks &tracks,
      double t0, double t1,
      double mixerLimit, 
      const AudioIOStartStreamOptions &options);
 
   void StopStream() override;
   void SeekStream(double seconds) { mSeek = seconds; }
 
   using PostRecordingAction = std::function<void()>;
   
 
   void CallAfterRecording(PostRecordingAction action);
 
public:
   wxString LastPaErrorString();
 
   wxLongLong GetLastPlaybackTime() const { return mLastPlaybackTimeMillis; }
   std::shared_ptr<AudacityProject> GetOwningProject() const
   { return mOwningProject.lock(); }
 
   void SetPaused(bool state);
 
   /* Mixer services are always available.  If no stream is running, these
    * methods use whatever device is specified by the preferences.  If a
    * stream *is* running, naturally they manipulate the mixer associated
    * with that stream.  If no mixer is available, output is emulated and
    * input is stuck at 1.0f (a gain is applied to output samples).
    */
   void SetMixer(int inputSource, float inputVolume,
                 float playbackVolume);
   void GetMixer(int *inputSource, float *inputVolume,
                 float *playbackVolume);
   bool InputMixerWorks();
 
   wxArrayString GetInputSourceNames();
 
   sampleFormat GetCaptureFormat() { return mCaptureFormat; }
   unsigned GetNumPlaybackChannels() const { return mNumPlaybackChannels; }
   unsigned GetNumCaptureChannels() const { return mNumCaptureChannels; }
 
   // Meaning really capturing, not just pre-rolling
   bool IsCapturing() const;
 
   static bool ValidateDeviceNames(const wxString &play, const wxString &rec);
 
   #ifdef EXPERIMENTAL_AUTOMATED_INPUT_LEVEL_ADJUSTMENT
      void AILAInitialize();
      void AILADisable();
      bool AILAIsActive();
      void AILAProcess(double maxPeak);
      void AILASetStartTime();
      double AILAGetLastDecisionTime();
   #endif
 
   bool IsAvailable(AudacityProject &project) const;
 
   double GetBestRate(bool capturing, bool playing, double sampleRate);
 
   double GetStreamTime();
 
   static void AudioThread(std::atomic<bool> &finish);
 
   static void Init();
   static void Deinit();
 
   void DelayActions(bool recording);
 
private:
 
   bool DelayingActions() const;
 
   void SetMeters();
 
   bool StartPortAudioStream(const AudioIOStartStreamOptions &options,
                             unsigned int numPlaybackChannels,
                             unsigned int numCaptureChannels,
                             sampleFormat captureFormat);
 
   void SetOwningProject( const std::shared_ptr<AudacityProject> &pProject );
   void ResetOwningProject();
 
   void TrackBufferExchange();
 
   void FillPlayBuffers();
   void TransformPlayBuffers(
      std::optional<RealtimeEffects::ProcessingScope> &scope);
   bool ProcessPlaybackSlices(
      std::optional<RealtimeEffects::ProcessingScope> &pScope,
      size_t available);
 
   void DrainRecordBuffers();
 
   size_t GetCommonlyFreePlayback();
 
   size_t GetCommonlyAvailCapture();
 
   bool AllocateBuffers(
      const AudioIOStartStreamOptions &options,
      const TransportTracks &tracks, double t0, double t1, double sampleRate );
 
   void StartStreamCleanup(bool bOnlyBuffers = false);
 
   std::mutex mPostRecordingActionMutex;
   PostRecordingAction mPostRecordingAction;
 
   bool mDelayingActions{ false };
};
 
#endif