AudioIO uses the PortAudio library to play and record sound. More...

#include <AudioIO.h>

Inheritance diagram for AudioIO:

Collaboration diagram for AudioIO:

Public Types
using	PostRecordingAction = std::function< void()>

Public Types inherited from AudioIoCallback
using	OldChannelGains = std::array< float, 2 >

using	RingBuffers = std::vector< std::unique_ptr< RingBuffer > >

Public Types inherited from Observer::Publisher< AudioIOEvent >
using	message_type = AudioIOEvent

using	CallbackReturn = std::conditional_t< true, void, bool >

using	Callback = std::function< CallbackReturn(const AudioIOEvent &) >
	Type of functions that can be connected to the Publisher. More...

Public Member Functions
std::shared_ptr< RealtimeEffectState >	AddState (AudacityProject &project, ChannelGroup *pGroup, const PluginID &id)
	Forwards to RealtimeEffectManager::AddState with proper init scope. More...

std::shared_ptr< RealtimeEffectState >	ReplaceState (AudacityProject &project, ChannelGroup *pGroup, size_t index, const PluginID &id)
	Forwards to RealtimeEffectManager::ReplaceState with proper init scope. More...

void	RemoveState (AudacityProject &project, ChannelGroup *pGroup, std::shared_ptr< RealtimeEffectState > pState)
	Forwards to RealtimeEffectManager::RemoveState with proper init scope. More...

void	StartMonitoring (const AudioIOStartStreamOptions &options)
	Start up Portaudio for capture and recording as needed for input monitoring and software playthrough only. More...

int	StartStream (const TransportSequences &sequences, double t0, double t1, double mixerLimit, const AudioIOStartStreamOptions &options)
	Start recording or playing back audio. More...

void	StopStream () override
	Stop recording, playback or input monitoring. More...

void	SeekStream (double seconds)
	Move the playback / recording position of the current stream by the specified amount from where it is now. More...

void	CallAfterRecording (PostRecordingAction action)
	Enqueue action for main thread idle time, not before the end of any recording in progress. More...

wxString	LastPaErrorString ()

wxLongLong	GetLastPlaybackTime () const

std::shared_ptr< AudacityProject >	GetOwningProject () const

void	SetPaused (bool state)
	Pause and un-pause playback and recording. More...

void	SetMixer (int inputSource, float inputVolume, float playbackVolume)

void	GetMixer (int inputSource, float inputVolume, float *playbackVolume)

bool	InputMixerWorks ()
	Find out if the input hardware level control is available. More...

wxArrayString	GetInputSourceNames ()
	Get the list of inputs to the current mixer device. More...

sampleFormat	GetCaptureFormat ()

size_t	GetNumPlaybackChannels () const

size_t	GetNumCaptureChannels () const

bool	IsCapturing () const

bool	IsAvailable (AudacityProject &project) const
	Function to automatically set an acceptable volume. More...

double	GetBestRate (bool capturing, bool playing, double sampleRate)
	Return a valid sample rate that is supported by the current I/O device(s). More...

double	GetStreamTime ()
	During playback, the sequence time most recently played. More...

void	DelayActions (bool recording)

Public Member Functions inherited from AudioIoCallback
	AudioIoCallback ()

	~AudioIoCallback ()

int	AudioCallback (constSamplePtr inputBuffer, float outputBuffer, unsigned long framesPerBuffer, const PaStreamCallbackTimeInfo timeInfo, const PaStreamCallbackFlags statusFlags, void *userData)

std::shared_ptr< AudioIOListener >	GetListener () const

void	SetListener (const std::shared_ptr< AudioIOListener > &listener)

int	CallbackDoSeek ()

void	CallbackCheckCompletion (int &callbackReturn, unsigned long len)

unsigned	CountSoloingSequences ()

bool	SequenceShouldBeSilent (const PlayableSequence &ps)

bool	SequenceHasBeenFadedOut (const OldChannelGains &gains)
	Returns true when playback buffer data from both channels is discardable. More...

bool	AllSequencesAlreadySilent ()

void	CheckSoundActivatedRecordingLevel (float *inputSamples, unsigned long framesPerBuffer)

void	AddToOutputChannel (unsigned int chan, float outputMeterFloats, float outputFloats, const float *tempBuf, bool drop, unsigned long len, const PlayableSequence &ps, float &channelGain)

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 ()
	Get the number of audio samples ready in all of the playback buffers. More...

size_t	GetCommonlyWrittenForPlayback ()

void	StartAudioThread ()

void	WaitForAudioThreadStarted ()

void	StopAudioThread ()

void	WaitForAudioThreadStopped ()

void	ProcessOnceAndWait (std::chrono::milliseconds sleepTime=std::chrono::milliseconds(50))

bool	HasRecordingException () const

const std::vector< std::pair< double, double > > &	LostCaptureIntervals ()

AudioIOExtRange	Extensions ()

Public Member Functions inherited from AudioIOBase
	AudioIOBase ()

virtual	~AudioIOBase ()

	AudioIOBase (const AudioIOBase &)=delete

AudioIOBase &	operator= (const AudioIOBase &)=delete

void	SetCaptureMeter (const std::shared_ptr< AudacityProject > &project, const std::weak_ptr< Meter > &meter)

void	SetPlaybackMeter (const std::shared_ptr< AudacityProject > &project, const std::weak_ptr< Meter > &meter)

void	HandleDeviceChange ()
	update state after changing what audio devices are selected More...

wxString	GetDeviceInfo () const
	Get diagnostic information on all the available audio I/O devices. More...

std::vector< AudioIODiagnostics >	GetAllDeviceInfo ()
	Get diagnostic information for audio devices and also for extensions. More...

bool	IsPaused () const
	Find out if playback / recording is currently paused. More...

virtual void	StopStream ()=0

bool	IsBusy () const
	Returns true if audio i/o is busy starting, stopping, playing, or recording. More...

bool	IsStreamActive () const
	Returns true if the audio i/o is running at all, but not during cleanup. More...

bool	IsStreamActive (int token) const

bool	IsAudioTokenActive (int token) const
	Returns true if the stream is active, or even if audio I/O is busy cleaning up its data or writing to disk. More...

bool	IsMonitoring () const
	Returns true if we're monitoring input (but not recording or playing actual audio) More...

void	SetMixer (int inputSource)

Public Member Functions inherited from Observer::Publisher< AudioIOEvent >
	Publisher (ExceptionPolicy *pPolicy=nullptr, Alloc a={})
	Constructor supporting type-erased custom allocation/deletion. More...

	Publisher (Publisher &&)=default

Publisher &	operator= (Publisher &&)=default

Subscription	Subscribe (Callback callback)
	Connect a callback to the Publisher; later-connected are called earlier. More...

Subscription	Subscribe (Object &obj, Return(Object::*callback)(Args...))
	Overload of Subscribe takes an object and pointer-to-member-function. More...

Static Public Member Functions
static AudioIO *	Get ()

static bool	ValidateDeviceNames (const wxString &play, const wxString &rec)
	Ensure selected device names are valid. More...

static void	AudioThread (std::atomic< bool > &finish)
	Sits in a thread loop reading and writing audio. More...

static void	Init ()

static void	Deinit ()

Static Public Member Functions inherited from AudioIOBase
static AudioIOBase *	Get ()

static std::vector< long >	GetSupportedPlaybackRates (int DevIndex=-1, double rate=0.0)
	Get a list of sample rates the output (playback) device supports. More...

static std::vector< long >	GetSupportedCaptureRates (int devIndex=-1, double rate=0.0)
	Get a list of sample rates the input (recording) device supports. More...

static std::vector< long >	GetSupportedSampleRates (int playDevice=-1, int recDevice=-1, double rate=0.0)
	Get a list of sample rates the current input/output device combination supports. More...

static int	GetOptimalSupportedSampleRate ()
	Get a supported sample rate which can be used a an optimal default. More...

Private Member Functions
	AudioIO ()

	~AudioIO ()

void	StartThread ()

bool	DelayingActions () const

void	SetMeters ()
	Set the current VU meters - this should be done once after each call to StartStream currently. More...

bool	StartPortAudioStream (const AudioIOStartStreamOptions &options, unsigned int numPlaybackChannels, unsigned int numCaptureChannels)
	Opens the portaudio stream(s) used to do playback or recording (or both) through. More...

void	SetOwningProject (const std::shared_ptr< AudacityProject > &pProject)

void	ResetOwningProject ()

void	SequenceBufferExchange ()

void	FillPlayBuffers ()
	First part of SequenceBufferExchange. More...

void	TransformPlayBuffers (std::optional< RealtimeEffects::ProcessingScope > &scope)

bool	ProcessPlaybackSlices (std::optional< RealtimeEffects::ProcessingScope > &pScope, size_t available)

void	DrainRecordBuffers ()
	Second part of SequenceBufferExchange. More...

size_t	GetCommonlyFreePlayback ()
	Get the number of audio samples free in all of the playback buffers. More...

size_t	GetCommonlyAvailCapture ()
	Get the number of audio samples ready in all of the recording buffers. More...

bool	AllocateBuffers (const AudioIOStartStreamOptions &options, const TransportSequences &sequences, double t0, double t1, double sampleRate)
	Allocate RingBuffer structures, and others, needed for playback and recording. More...

void	StartStreamCleanup (bool bOnlyBuffers=false)
	Clean up after StartStream if it fails. More...

Private Attributes
std::mutex	mPostRecordingActionMutex

PostRecordingAction	mPostRecordingAction

bool	mDelayingActions { false }

Additional Inherited Members
Public Attributes inherited from AudioIoCallback
int	mbHasSoloSequences

int	mCallbackReturn

long	mNumPauseFrames
	How many frames of zeros were output due to pauses? More...

std::thread	mAudioThread

std::atomic< bool >	mFinishAudioThread { false }

std::vector< std::unique_ptr< Resample > >	mResample

RingBuffers	mCaptureBuffers

RecordableSequences	mCaptureSequences

RingBuffers	mPlaybackBuffers

ConstPlayableSequences	mPlaybackSequences

std::vector< OldChannelGains >	mOldChannelGains

std::vector< SampleBuffer >	mScratchBuffers

std::vector< float * >	mScratchPointers
	pointing into mScratchBuffers More...

std::vector< std::unique_ptr< Mixer > >	mPlaybackMixers

std::atomic< float >	mMixerOutputVol { 1.0 }

double	mFactor

unsigned long	mMaxFramesOutput

bool	mbMicroFades

double	mSeek

PlaybackPolicy::Duration	mPlaybackRingBufferSecs

double	mCaptureRingBufferSecs

size_t	mPlaybackSamplesToCopy
	Preferred batch size for replenishing the playback RingBuffer. More...

size_t	mHardwarePlaybackLatencyFrames {}
	Hardware output latency in frames. More...

size_t	mPlaybackQueueMinimum
	Occupancy of the queue we try to maintain, with bigger batches if needed. More...

double	mMinCaptureSecsToCopy

bool	mSoftwarePlaythrough

bool	mPauseRec
	True if Sound Activated Recording is enabled. More...

float	mSilenceLevel

size_t	mNumCaptureChannels

size_t	mNumPlaybackChannels

sampleFormat	mCaptureFormat

double	mCaptureRate {}

unsigned long long	mLostSamples { 0 }

std::atomic< bool >	mAudioThreadShouldCallSequenceBufferExchangeOnce

std::atomic< bool >	mAudioThreadSequenceBufferExchangeLoopRunning

std::atomic< bool >	mAudioThreadSequenceBufferExchangeLoopActive

std::atomic< Acknowledge >	mAudioThreadAcknowledge

std::atomic< bool >	mForceFadeOut { false }

wxLongLong	mLastPlaybackTimeMillis

double	mLastRecordingOffset
	Not (yet) used; should perhaps be atomic when it is. More...

PaError	mLastPaError

bool	mSimulateRecordingErrors { false }

std::atomic< bool >	mDetectUpstreamDropouts { true }

Static Public Attributes inherited from AudioIoCallback
static int	mNextStreamToken = 0

Static Public Attributes inherited from AudioIOBase
static const int	StandardRates []
	Array of common audio sample rates. More...

static const int	NumStandardRates = WXSIZEOF(AudioIOBase::StandardRates)
	How many standard sample rates there are. More...

Static Public Attributes inherited from Observer::Publisher< AudioIOEvent >
static constexpr bool	notifies_all

Protected Member Functions inherited from AudioIoCallback
float	GetMixerOutputVol ()

void	SetMixerOutputVol (float value)

void	SetRecordingException ()

void	ClearRecordingException ()

Protected Member Functions inherited from Observer::Publisher< AudioIOEvent >
CallbackReturn	Publish (const AudioIOEvent &message)
	Send a message to connected callbacks. More...

Static Protected Member Functions inherited from AudioIoCallback
static size_t	MinValue (const RingBuffers &buffers, size_t(RingBuffer::*pmf)() const)

Static Protected Member Functions inherited from AudioIOBase
static wxString	DeviceName (const PaDeviceInfo *info)

static wxString	HostName (const PaDeviceInfo *info)

static int	getRecordDevIndex (const wxString &devName={})
	get the index of the supplied (named) recording device, or the device selected in the preferences if none given. More...

static int	getPlayDevIndex (const wxString &devName={})
	get the index of the device selected in the preferences. More...

Protected Attributes inherited from AudioIoCallback
std::weak_ptr< AudioIOListener >	mListener

bool	mUsingAlsa { false }

bool	mUsingJack { false }

wxMutex	mSuspendAudioThread

wxAtomicInt	mRecordingException {}

std::vector< std::pair< double, double > >	mLostCaptureIntervals

bool	mDetectDropouts { true }

RecordingSchedule	mRecordingSchedule {}

PlaybackSchedule	mPlaybackSchedule

std::unique_ptr< TransportState >	mpTransportState
	Holds some state for duration of playback or recording. More...

Protected Attributes inherited from AudioIOBase
std::weak_ptr< AudacityProject >	mOwningProject

std::atomic< bool >	mPaused { false }
	True if audio playback is paused. More...

int	mStreamToken { 0 }

double	mRate
	Audio playback rate in samples per second. More...

PaStream *	mPortStreamV19

std::weak_ptr< Meter >	mInputMeter {}

std::weak_ptr< Meter >	mOutputMeter {}

bool	mInputMixerWorks
	Can we control the hardware input level? More...

std::vector< std::unique_ptr< AudioIOExtBase > >	mAudioIOExt

Static Protected Attributes inherited from AudioIoCallback
static double	mCachedBestRateOut

static bool	mCachedBestRatePlaying

static bool	mCachedBestRateCapturing

Static Protected Attributes inherited from AudioIOBase
static std::unique_ptr< AudioIOBase >	ugAudioIO

static int	mCachedPlaybackIndex = -1

static std::vector< long >	mCachedPlaybackRates

static int	mCachedCaptureIndex = -1

static std::vector< long >	mCachedCaptureRates

static std::vector< long >	mCachedSampleRates

static double	mCachedBestRateIn = 0.0

static const int	RatesToTry []
	Array of audio sample rates to try to use. More...

static const int	NumRatesToTry = WXSIZEOF(AudioIOBase::RatesToTry)
	How many sample rates to try. More...

Detailed Description

AudioIO uses the PortAudio library to play and record sound.

Great care and attention to detail are necessary for understanding and modifying this system. The code in this file is run from three different thread contexts: the UI thread, the disk thread (which this file creates and maintains; in the code, this is called the Audio Thread), and the PortAudio callback thread. To highlight this deliniation, the file is divided into three parts based on what thread context each function is intended to run in.

Todo:: run through all functions called from audio and portaudio threads to verify they are thread-safe. Note that synchronization of the style: "A sets flag to signal B, B clears flag to acknowledge completion" is not thread safe in a general multiple-CPU context. For example, B can write to a buffer and set a completion flag. The flag write can occur before the buffer write due to out-of-order execution. Then A can see the flag and read the buffer before buffer writes complete.

Definition at line 421 of file AudioIO.h.

Member Typedef Documentation

◆ PostRecordingAction

using AudioIO::PostRecordingAction = std::function<void()>

Definition at line 492 of file AudioIO.h.

Constructor & Destructor Documentation

◆ AudioIO()

AudioIO::AudioIO ( )

private

Definition at line 232 of file AudioIO.cpp.

{
   if (!std::atomic<double>{}.is_lock_free()) {
      // If this check fails, then the atomic<double> members in AudioIO.h
      // might be changed to atomic<float> to be more efficient with some
      // loss of precision.  That could be conditionally compiled depending
      // on the platform.
      wxASSERT(false);
   }
 
   // This ASSERT because of casting in the callback
   // functions where we cast a tempFloats buffer to a (short*) buffer.
   // We have to ASSERT in the GUI thread, if we are to see it properly.
   wxASSERT( sizeof( short ) <= sizeof( float ));
 
   mAudioThreadShouldCallSequenceBufferExchangeOnce
      .store(false, std::memory_order_relaxed);
   mAudioThreadSequenceBufferExchangeLoopRunning
      .store(false, std::memory_order_relaxed);
   mAudioThreadSequenceBufferExchangeLoopActive
      .store(false, std::memory_order_relaxed);
 
   mAudioThreadAcknowledge.store(Acknowledge::eNone, std::memory_order_relaxed);
 
   mPortStreamV19 = NULL;
 
   mNumPauseFrames = 0;
 
#ifdef EXPERIMENTAL_AUTOMATED_INPUT_LEVEL_ADJUSTMENT
   mAILAActive = false;
#endif
 
   mLastPaError = paNoError;
 
   mLastRecordingOffset = 0.0;
   mNumCaptureChannels = 0;
   mSilenceLevel = 0.0;
 
   mOutputMeter.reset();
 
   PaError err = Pa_Initialize();
 
   if (err != paNoError) {
      auto errStr = XO("Could not find any audio devices.\n");
      errStr += XO("You will not be able to play or record audio.\n\n");
      wxString paErrStr = LAT1CTOWX(Pa_GetErrorText(err));
      if (!paErrStr.empty())
         errStr += XO("Error: %s").Format( paErrStr );
      // XXX: we are in libaudacity, popping up dialogs not allowed!  A
      // long-term solution will probably involve exceptions
      using namespace BasicUI;
      ShowMessageBox(
         errStr,
         MessageBoxOptions{}
            .Caption(XO("Error Initializing Audio"))
            .IconStyle(Icon::Error)
            .ButtonStyle(Button::Ok));
 
      // Since PortAudio is not initialized, all calls to PortAudio
      // functions will fail.  This will give reasonable behavior, since
      // the user will be able to do things not relating to audio i/o,
      // but any attempt to play or record will simply fail.
   }
 
#if defined(USE_PORTMIXER)
   mPortMixer = NULL;
   mPreviousHWPlaythrough = -1.0;
   HandleDeviceChange();
#else
   mInputMixerWorks = false;
#endif
 
   SetMixerOutputVol(AudioIOPlaybackVolume.Read());
 
   mLastPlaybackTimeMillis = 0;
}

References AudioIOPlaybackVolume, BasicUI::MessageBoxOptions::Caption(), eNone, AudioIOBase::HandleDeviceChange(), LAT1CTOWX, AudioIoCallback::mAudioThreadAcknowledge, AudioIoCallback::mAudioThreadSequenceBufferExchangeLoopActive, AudioIoCallback::mAudioThreadSequenceBufferExchangeLoopRunning, AudioIoCallback::mAudioThreadShouldCallSequenceBufferExchangeOnce, AudioIOBase::mInputMixerWorks, AudioIoCallback::mLastPaError, AudioIoCallback::mLastPlaybackTimeMillis, AudioIoCallback::mLastRecordingOffset, AudioIoCallback::mNumCaptureChannels, AudioIoCallback::mNumPauseFrames, AudioIOBase::mOutputMeter, AudioIOBase::mPortStreamV19, AudioIoCallback::mSilenceLevel, Setting< T >::Read(), AudioIoCallback::SetMixerOutputVol(), BasicUI::ShowMessageBox(), and XO().

Referenced by Init().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ~AudioIO()

AudioIO::~AudioIO ( )

private

Definition at line 314 of file AudioIO.cpp.

{
   if ( !mOwningProject.expired() )
      // Unlikely that this will be destroyed earlier than any projects, but
      // be prepared anyway
      ResetOwningProject();
 
#if defined(USE_PORTMIXER)
   if (mPortMixer) {
      #if __WXMAC__
      if (Px_SupportsPlaythrough(mPortMixer) && mPreviousHWPlaythrough >= 0.0)
         Px_SetPlaythrough(mPortMixer, mPreviousHWPlaythrough);
         mPreviousHWPlaythrough = -1.0;
      #endif
      Px_CloseMixer(mPortMixer);
      mPortMixer = NULL;
   }
#endif
 
   // FIXME: ? TRAP_ERR.  Pa_Terminate probably OK if err without reporting.
   Pa_Terminate();
 
   /* Delete is a "graceful" way to stop the thread.
      (Kill is the not-graceful way.) */
 
   // This causes reentrancy issues during application shutdown
   // wxTheApp->Yield();
 
   mFinishAudioThread.store(true, std::memory_order_release);
   mAudioThread.join();
}

References AudioIoCallback::mAudioThread, AudioIoCallback::mFinishAudioThread, AudioIOBase::mOwningProject, and ResetOwningProject().

Here is the call graph for this function:

Member Function Documentation

◆ AddState()

std::shared_ptr< RealtimeEffectState > AudioIO::AddState	(	AudacityProject &	project,
		ChannelGroup *	pGroup,
		const PluginID &	id
	)

Forwards to RealtimeEffectManager::AddState with proper init scope.

Postcondition: result: !result || result->GetEffect() != nullptr

Definition at line 347 of file AudioIO.cpp.

{
   RealtimeEffects::InitializationScope *pInit = nullptr;
   if (mpTransportState && mpTransportState->mpRealtimeInitialization)
      if (auto pProject = GetOwningProject(); pProject.get() == &project)
         pInit = &*mpTransportState->mpRealtimeInitialization;
   return RealtimeEffectManager::Get(project).AddState(pInit, pGroup, id);
}

References RealtimeEffectManager::AddState(), RealtimeEffectManager::Get(), GetOwningProject(), AudioIoCallback::mpTransportState, and project.

Referenced by EffectUIHost::InitializeInstance().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ AllocateBuffers()

bool AudioIO::AllocateBuffers	(	const AudioIOStartStreamOptions &	options,
		const TransportSequences &	sequences,
		double	t0,
		double	t1,
		double	sampleRate
	)

private

Allocate RingBuffer structures, and others, needed for playback and recording.

Returns true iff successful.

Definition at line 1166 of file AudioIO.cpp.

{
   bool success = false;
   auto cleanup = finally([&]{
      if (!success) StartStreamCleanup( false );
   });
 
   auto &policy = mPlaybackSchedule.GetPolicy();
   auto times = policy.SuggestedBufferTimes(mPlaybackSchedule);
 
   //
   // The (audio) stream has been opened successfully (assuming we tried
   // to open it). We now proceed to
   // allocate the memory structures the stream will need.
   //
 
   //
   // The RingBuffer sizes, and the max amount of the buffer to
   // fill at a time, both grow linearly with the number of
   // sequences.  This allows us to scale up to many sequences without
   // killing performance.
   //
 
   // real playback time to produce with each filling of the buffers
   // by the Audio thread (except at the end of playback):
   // usually, make fillings fewer and longer for less CPU usage.
   // What Audio thread produces for playback is then consumed by the PortAudio
   // thread, in many smaller pieces.
   double playbackTime = lrint(times.batchSize.count() * mRate) / mRate;
 
   wxASSERT( playbackTime >= 0 );
   mPlaybackSamplesToCopy = playbackTime * mRate;
 
   // Capacity of the playback buffer.
   mPlaybackRingBufferSecs = times.ringBufferDelay;
 
   mCaptureRingBufferSecs =
      4.5 + 0.5 * std::min(size_t(16), mNumCaptureChannels);
   mMinCaptureSecsToCopy =
      0.2 + 0.2 * std::min(size_t(16), mNumCaptureChannels);
 
   bool bDone;
   do
   {
      bDone = true; // assume success
      try
      {
         if( mNumPlaybackChannels > 0 ) {
            // Allocate output buffers.
            // Allow at least 2x of the buffer latency.
            auto playbackBufferSize =
               std::max((size_t)lrint(mRate * mPlaybackRingBufferSecs.count()), mHardwarePlaybackLatencyFrames * 2);
 
            // Make playbackBufferSize a multiple of mPlaybackSamplesToCopy
            playbackBufferSize = mPlaybackSamplesToCopy *
               ((playbackBufferSize + mPlaybackSamplesToCopy - 1) / mPlaybackSamplesToCopy);
 
            // Adjust mPlaybackRingBufferSecs correspondingly
            mPlaybackRingBufferSecs = PlaybackPolicy::Duration { playbackBufferSize / mRate };
 
            const size_t totalWidth = std::accumulate(
               mPlaybackSequences.begin(), mPlaybackSequences.end(), 0,
               [](size_t acc, const auto &pSequence){
                  return acc + pSequence->NChannels(); });
 
            // mPlaybackBuffers buffers correspond many-to-one with
            // mPlaybackSequences
            // Except, always make at least one playback buffer, in case of
            // MIDI playback without any audio
            mPlaybackBuffers.resize(0);
            mPlaybackBuffers.resize(
               std::max<size_t>(1, totalWidth));
            // Number of scratch buffers depends on device playback channels
            if (mNumPlaybackChannels > 0) {
               mScratchBuffers.resize(mNumPlaybackChannels * 2 + 1);
               mScratchPointers.clear();
               for (auto &buffer : mScratchBuffers) {
                  buffer.Allocate(playbackBufferSize, floatSample);
                  mScratchPointers.push_back(
                     reinterpret_cast<float*>(buffer.ptr()));
               }
            }
            mPlaybackMixers.clear();
 
            const auto &warpOptions =
               policy.MixerWarpOptions(mPlaybackSchedule);
 
            mPlaybackQueueMinimum = lrint( mRate * times.latency.count() );
            mPlaybackQueueMinimum =
               std::min( mPlaybackQueueMinimum, playbackBufferSize );
 
            // Limit the mPlaybackQueueMinimum to the hardware latency
            mPlaybackQueueMinimum =
               std::max(mPlaybackQueueMinimum, mHardwarePlaybackLatencyFrames);
 
            // Make mPlaybackQueueMinimum a multiple of mPlaybackSamplesToCopy
            mPlaybackQueueMinimum = mPlaybackSamplesToCopy *
               ((mPlaybackQueueMinimum + mPlaybackSamplesToCopy - 1) / mPlaybackSamplesToCopy);
 
            if (mPlaybackSequences.empty())
               // Make at least one playback buffer
               mPlaybackBuffers[0] =
                  std::make_unique<RingBuffer>(floatSample, playbackBufferSize);
 
            mOldChannelGains.resize(mPlaybackSequences.size());
            size_t iBuffer = 0;
            for (unsigned int i = 0; i < mPlaybackSequences.size(); i++) {
               const auto &pSequence = mPlaybackSequences[i];
               // Bug 1763 - We must fade in from zero to avoid a click on starting.
               mOldChannelGains[i][0] = 0.0;
               mOldChannelGains[i][1] = 0.0;
 
               for (size_t jj = 0, nChannels = pSequence->NChannels();
                  jj < nChannels; ++jj
               )
                  mPlaybackBuffers[iBuffer++] = std::make_unique<RingBuffer>(
                     floatSample, playbackBufferSize);
 
               // By the precondition of StartStream which is sole caller of
               // this function:
               assert(pSequence->FindChannelGroup());
               // use sequence time for the end time, not real time!
               double startTime, endTime;
               if (!sequences.prerollSequences.empty())
                  startTime = mPlaybackSchedule.mT0;
               else
                  startTime = t0;
 
               if (make_iterator_range(sequences.prerollSequences)
                  .contains(pSequence))
                  // Stop playing this sequence after pre-roll
                  endTime = t0;
               else
                  // Pass t1 -- not mT1 as may have been adjusted for latency
                  // -- so that overdub recording stops playing back samples
                  // at the right time, though transport may continue to
                  // record
                  endTime = t1;
 
               Mixer::Inputs mixSequences;
               mixSequences.push_back(Mixer::Input{ pSequence });
               mPlaybackMixers.emplace_back(std::make_unique<Mixer>(
                  move(mixSequences),
                  // Don't throw for read errors, just play silence:
                  false,
                  warpOptions, startTime, endTime, pSequence->NChannels(),
                  std::max( mPlaybackSamplesToCopy, mPlaybackQueueMinimum ),
                  false, // not interleaved
                  mRate, floatSample,
                  false, // low quality dithering and resampling
                  nullptr, // no custom mix-down
                  Mixer::ApplyGain::Discard // don't apply gains
               ));
            }
 
            const auto timeQueueSize = 1 +
               (playbackBufferSize + TimeQueueGrainSize - 1)
                  / TimeQueueGrainSize;
            mPlaybackSchedule.mTimeQueue.Resize( timeQueueSize );
         }
 
         if( mNumCaptureChannels > 0 )
         {
            // Allocate input buffers.  For every input sequence we allocate
            // a ring buffer of five seconds
            auto captureBufferSize =
               (size_t)(mRate * mCaptureRingBufferSecs + 0.5);
 
            // In the extraordinarily rare case that we can't even afford
            // 100 samples, just give up.
            if(captureBufferSize < 100)
            {
               BasicUI::ShowMessageBox( XO("Out of memory!") );
               return false;
            }
 
            mCaptureBuffers.resize(0);
            mCaptureBuffers.resize(mNumCaptureChannels);
            mResample.resize(0);
            mResample.resize(mNumCaptureChannels);
            mFactor = sampleRate / mRate;
 
            for (unsigned int i = 0; i < mNumCaptureChannels; ++i) {
               mCaptureBuffers[i] = std::make_unique<RingBuffer>(
                  mCaptureFormat, captureBufferSize);
               mResample[i] =
                  std::make_unique<Resample>(true, mFactor, mFactor);
                  // constant rate resampling
            }
         }
      }
      catch(std::bad_alloc&)
      {
         // Oops!  Ran out of memory.  This is pretty rare, so we'll just
         // try deleting everything, halving our buffer size, and try again.
         StartStreamCleanup(true);
         mPlaybackRingBufferSecs *= 0.5;
         mPlaybackSamplesToCopy /= 2;
         mCaptureRingBufferSecs *= 0.5;
         mMinCaptureSecsToCopy *= 0.5;
         bDone = false;
 
         // In the extraordinarily rare case that we can't even afford 100
         // samples, just give up.
         auto playbackBufferSize =
            (size_t)lrint(mRate * mPlaybackRingBufferSecs.count());
         if(playbackBufferSize < 100 || mPlaybackSamplesToCopy < 100)
         {
            BasicUI::ShowMessageBox( XO("Out of memory!") );
            return false;
         }
      }
   } while(!bDone);
 
   success = true;
   return true;
}

Referenced by StartStream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ AudioThread()

void AudioIO::AudioThread ( std::atomic< bool > & finish )

static

Sits in a thread loop reading and writing audio.

Definition at line 1797 of file AudioIO.cpp.

{
   enum class State { eUndefined, eOnce, eLoopRunning, eDoNothing, eMonitoring } lastState = State::eUndefined;
   AudioIO *const gAudioIO = AudioIO::Get();
   while (!finish.load(std::memory_order_acquire)) {
      using Clock = std::chrono::steady_clock;
      auto loopPassStart = Clock::now();
      auto &schedule = gAudioIO->mPlaybackSchedule;
      const auto interval = schedule.GetPolicy().SleepInterval(schedule);
 
      // Set LoopActive outside the tests to avoid race condition
      gAudioIO->mAudioThreadSequenceBufferExchangeLoopActive
         .store(true, std::memory_order_relaxed);
      if( gAudioIO->mAudioThreadShouldCallSequenceBufferExchangeOnce
         .load(std::memory_order_acquire) )
      {
         gAudioIO->SequenceBufferExchange();
         gAudioIO->mAudioThreadShouldCallSequenceBufferExchangeOnce
            .store(false, std::memory_order_release);
 
         lastState = State::eOnce;
      }
      else if( gAudioIO->mAudioThreadSequenceBufferExchangeLoopRunning
         .load(std::memory_order_relaxed))
      {
         if (lastState != State::eLoopRunning)
         {
            // Main thread has told us to start - acknowledge that we do
            gAudioIO->mAudioThreadAcknowledge.store(Acknowledge::eStart,
                                                    std::memory_order::memory_order_release);
         }
         lastState = State::eLoopRunning;
 
         // We call the processing after raising the acknowledge flag, because the main thread
         // only needs to know that the message was seen.
         //
         // This is unlike the case with mAudioThreadShouldCallSequenceBufferExchangeOnce where the
         // store really means that the one-time exchange was done.
 
         gAudioIO->SequenceBufferExchange();
      }
      else
      {
         if (    (lastState == State::eLoopRunning)
              || (lastState == State::eMonitoring ) )
         {
            // Main thread has told us to stop; (actually: to neither process "once" nor "loop running")
            // acknowledge that we received the order and that no more processing will be done.
            gAudioIO->mAudioThreadAcknowledge.store(Acknowledge::eStop,
                                                    std::memory_order::memory_order_release);
         }
         lastState = State::eDoNothing;
 
         if (gAudioIO->IsMonitoring())
         {
            lastState = State::eMonitoring;
         }
      }
 
      gAudioIO->mAudioThreadSequenceBufferExchangeLoopActive
         .store(false, std::memory_order_relaxed);
 
      std::this_thread::sleep_until( loopPassStart + interval );
   }
}

References eStart, eStop, Get(), PlaybackSchedule::GetPolicy(), AudioIOBase::IsMonitoring(), AudioIoCallback::mAudioThreadAcknowledge, AudioIoCallback::mAudioThreadSequenceBufferExchangeLoopActive, AudioIoCallback::mAudioThreadSequenceBufferExchangeLoopRunning, AudioIoCallback::mAudioThreadShouldCallSequenceBufferExchangeOnce, AudioIoCallback::mPlaybackSchedule, SequenceBufferExchange(), and PlaybackPolicy::SleepInterval().

Referenced by StartThread().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CallAfterRecording()

void AudioIO::CallAfterRecording ( PostRecordingAction action )

Enqueue action for main thread idle time, not before the end of any recording in progress.

This may be called from non-main threads

Definition at line 1138 of file AudioIO.cpp.

{
   if (!action)
      return;
 
   {
      std::lock_guard<std::mutex> guard{ mPostRecordingActionMutex };
      if (mPostRecordingAction) {
         // Enqueue it, even if perhaps not still recording,
         // but it wasn't cleared yet
         mPostRecordingAction = [
            prevAction = std::move(mPostRecordingAction),
            nextAction = std::move(action)
         ]{ prevAction(); nextAction(); };
         return;
      }
      else if (DelayingActions()) {
         mPostRecordingAction = std::move(action);
         return;
      }
   }
 
   // Don't delay it except until idle time.
   // (Recording might start between now and then, but won't go far before
   // the action is done.  So the system isn't bulletproof yet.)
   BasicUI::CallAfter(move(action));
}

References BasicUI::CallAfter(), DelayingActions(), mPostRecordingAction, and mPostRecordingActionMutex.

Here is the call graph for this function:

◆ Deinit()

void AudioIO::Deinit ( )

static

Definition at line 218 of file AudioIO.cpp.

{
   ugAudioIO.reset();
}

References AudioIOBase::ugAudioIO.

Referenced by AudacityApp::OnExit().

Here is the caller graph for this function:

◆ DelayActions()

void AudioIO::DelayActions ( bool recording )

For purposes of CallAfterRecording, treat time from now as if recording (when argument is true) or not necessarily so (false)

Definition at line 1128 of file AudioIO.cpp.

{
   mDelayingActions = recording;
}

References mDelayingActions.

Referenced by StopStream().

Here is the caller graph for this function:

◆ DelayingActions()

bool AudioIO::DelayingActions ( ) const

private

Definition at line 1133 of file AudioIO.cpp.

{
   return mDelayingActions || (mPortStreamV19 && mNumCaptureChannels > 0);
}

References mDelayingActions, AudioIoCallback::mNumCaptureChannels, and AudioIOBase::mPortStreamV19.

Referenced by CallAfterRecording().

Here is the caller graph for this function:

◆ DrainRecordBuffers()

void AudioIO::DrainRecordBuffers ( )

private

Second part of SequenceBufferExchange.

Definition at line 2118 of file AudioIO.cpp.

{
   if (mRecordingException || mCaptureSequences.empty())
      return;
 
   auto delayedHandler = [this] ( AudacityException * pException ) {
      // In the main thread, stop recording
      // This is one place where the application handles disk
      // exhaustion exceptions from RecordableSequence operations, without
      // rolling back to the last pushed undo state.  Instead, partial recording
      // results are pushed as a NEW undo state.  For this reason, as
      // commented elsewhere, we want an exception safety guarantee for
      // the output RecordableSequences, after the failed append operation, that
      // the sequences remain as they were after the previous successful
      // (block-level) appends.
 
      // Note that the Flush in StopStream() may throw another exception,
      // but StopStream() contains that exception, and the logic in
      // AudacityException::DelayedHandlerAction prevents redundant message
      // boxes.
      StopStream();
      DefaultDelayedHandlerAction( pException );
      for (auto &pSequence: mCaptureSequences)
         pSequence->RepairChannels();
   };
 
   GuardedCall( [&] {
      // start record buffering
      const auto avail = GetCommonlyAvailCapture(); // samples
      const auto remainingTime =
         std::max(0.0, mRecordingSchedule.ToConsume());
      // This may be a very big double number:
      const auto remainingSamples = remainingTime * mRate;
      bool latencyCorrected = true;
 
      double deltat = avail / mRate;
 
      if (mAudioThreadShouldCallSequenceBufferExchangeOnce
          .load(std::memory_order_relaxed) ||
          deltat >= mMinCaptureSecsToCopy)
      {
         bool newBlocks = false;
 
         // Append captured samples to the end of the RecordableSequences.
         // (WaveTracks have their own buffering for efficiency.)
         auto iter = mCaptureSequences.begin();
         auto width = (*iter)->NChannels();
         size_t iChannel = 0;
         for (size_t i = 0; i < mNumCaptureChannels; ++i) {
            Finally Do {[&]{
               if (++iChannel == width) {
                  ++iter;
                  iChannel = 0;
                  if (iter != mCaptureSequences.end())
                     width = (*iter)->NChannels();
               }
            }};
            size_t discarded = 0;
 
            if (!mRecordingSchedule.mLatencyCorrected) {
               const auto correction = mRecordingSchedule.TotalCorrection();
               if (correction >= 0) {
                  // Rightward shift
                  // Once only (per sequence per recording), insert some initial
                  // silence.
                  size_t size = floor( correction * mRate * mFactor);
                  SampleBuffer temp(size, mCaptureFormat);
                  ClearSamples(temp.ptr(), mCaptureFormat, 0, size);
                  (*iter)->Append(iChannel, temp.ptr(), mCaptureFormat, size, 1,
                     // Do not dither recordings
                     narrowestSampleFormat);
               }
               else {
                  // Leftward shift
                  // discard some samples from the ring buffers.
                  size_t size = floor(
                     mRecordingSchedule.ToDiscard() * mRate );
 
                  // The ring buffer might have grown concurrently -- don't discard more
                  // than the "avail" value noted above.
                  discarded = mCaptureBuffers[i]->Discard(std::min(avail, size));
 
                  if (discarded < size)
                     // We need to visit this again to complete the
                     // discarding.
                     latencyCorrected = false;
               }
            }
 
            const float *pCrossfadeSrc = nullptr;
            size_t crossfadeStart = 0, totalCrossfadeLength = 0;
            if (i < mRecordingSchedule.mCrossfadeData.size())
            {
               // Do crossfading
               // The supplied crossfade samples are at the same rate as the
               // sequence
               const auto &data = mRecordingSchedule.mCrossfadeData[i];
               totalCrossfadeLength = data.size();
               if (totalCrossfadeLength) {
                  crossfadeStart =
                     floor(mRecordingSchedule.Consumed() * mCaptureRate);
                  if (crossfadeStart < totalCrossfadeLength)
                     pCrossfadeSrc = data.data() + crossfadeStart;
               }
            }
 
            wxASSERT(discarded <= avail);
            size_t toGet = avail - discarded;
            SampleBuffer temp;
            size_t size;
            sampleFormat format;
            if( mFactor == 1.0 )
            {
               // Take captured samples directly
               size = toGet;
               if (pCrossfadeSrc)
                  // Change to float for crossfade calculation
                  format = floatSample;
               else
                  format = mCaptureFormat;
               temp.Allocate(size, format);
               const auto got =
                  mCaptureBuffers[i]->Get(temp.ptr(), format, toGet);
               // wxASSERT(got == toGet);
               // but we can't assert in this thread
               wxUnusedVar(got);
               if (double(size) > remainingSamples)
                  size = floor(remainingSamples);
            }
            else
            {
               size = lrint(toGet * mFactor);
               format = floatSample;
               SampleBuffer temp1(toGet, floatSample);
               temp.Allocate(size, format);
               const auto got =
                  mCaptureBuffers[i]->Get(temp1.ptr(), floatSample, toGet);
               // wxASSERT(got == toGet);
               // but we can't assert in this thread
               wxUnusedVar(got);
               /* we are re-sampling on the fly. The last resampling call
                * must flush any samples left in the rate conversion buffer
                * so that they get recorded
                */
               if (toGet > 0 ) {
                  if (double(toGet) > remainingSamples)
                     toGet = floor(remainingSamples);
                  const auto results =
                  mResample[i]->Process(mFactor, (float *)temp1.ptr(), toGet,
                                        !IsStreamActive(), (float *)temp.ptr(), size);
                  size = results.second;
               }
            }
 
            if (pCrossfadeSrc) {
               wxASSERT(format == floatSample);
               size_t crossfadeLength = std::min(size, totalCrossfadeLength - crossfadeStart);
               if (crossfadeLength) {
                  auto ratio = double(crossfadeStart) / totalCrossfadeLength;
                  auto ratioStep = 1.0 / totalCrossfadeLength;
                  auto pCrossfadeDst = (float*)temp.ptr();
 
                  // Crossfade loop here
                  for (size_t ii = 0; ii < crossfadeLength; ++ii) {
                     *pCrossfadeDst = ratio * *pCrossfadeDst + (1.0 - ratio) * *pCrossfadeSrc;
                     ++pCrossfadeSrc, ++pCrossfadeDst;
                     ratio += ratioStep;
                  }
               }
            }
 
            // Now append
            // see comment in second handler about guarantee
            newBlocks = (*iter)->Append(iChannel,
               temp.ptr(), format, size, 1,
               // Do not dither recordings
               narrowestSampleFormat
            ) || newBlocks;
         } // end loop over capture channels
 
         // Now update the recording schedule position
         mRecordingSchedule.mPosition += avail / mRate;
         mRecordingSchedule.mLatencyCorrected = latencyCorrected;
 
         auto pListener = GetListener();
         if (pListener && newBlocks)
            pListener->OnAudioIONewBlocks();
 
      }
      // end of record buffering
   },
   // handler
   [this] ( AudacityException *pException ) {
      if ( pException ) {
         // So that we don't attempt to fill the recording buffer again
         // before the main thread stops recording
         SetRecordingException();
         return ;
      }
      else
         // Don't want to intercept other exceptions (?)
         throw;
   },
   delayedHandler );
}

References SampleBuffer::Allocate(), ClearSamples(), RecordingSchedule::Consumed(), DefaultDelayedHandlerAction(), floatSample, anonymous_namespace{ExportPCM.cpp}::format, GetCommonlyAvailCapture(), AudioIoCallback::GetListener(), GuardedCall(), anonymous_namespace{StretchingSequenceIntegrationTest.cpp}::iChannel, AudioIOBase::IsStreamActive(), lrint, AudioIoCallback::mAudioThreadShouldCallSequenceBufferExchangeOnce, AudioIoCallback::mCaptureBuffers, AudioIoCallback::mCaptureFormat, AudioIoCallback::mCaptureRate, AudioIoCallback::mCaptureSequences, RecordingSchedule::mCrossfadeData, AudioIoCallback::mFactor, min(), RecordingSchedule::mLatencyCorrected, AudioIoCallback::mMinCaptureSecsToCopy, AudioIoCallback::mNumCaptureChannels, RecordingSchedule::mPosition, AudioIOBase::mRate, AudioIoCallback::mRecordingException, AudioIoCallback::mRecordingSchedule, AudioIoCallback::mResample, narrowestSampleFormat, SampleBuffer::ptr(), AudioIoCallback::SetRecordingException(), size, StopStream(), RecordingSchedule::ToConsume(), RecordingSchedule::ToDiscard(), and RecordingSchedule::TotalCorrection().

Referenced by SequenceBufferExchange().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ FillPlayBuffers()

void AudioIO::FillPlayBuffers ( )

private

First part of SequenceBufferExchange.

Definition at line 1904 of file AudioIO.cpp.

{
   std::optional<RealtimeEffects::ProcessingScope> pScope;
   if (mpTransportState && mpTransportState->mpRealtimeInitialization)
      pScope.emplace(
         *mpTransportState->mpRealtimeInitialization, mOwningProject);
 
   if (mNumPlaybackChannels == 0)
      return;
 
   // It is possible that some buffers will have more samples available than
   // others.  This could happen if we hit this code during the PortAudio
   // callback.  Also, if in a previous pass, unequal numbers of samples were
   // discarded from ring buffers for differing latencies.
 
   // To keep things simple, we write no more data than is vacant in
   // ALL buffers, and advance the global time by that much.
   auto nAvailable = GetCommonlyFreePlayback();
 
   // Don't fill the buffers at all unless we can do
   // at least mPlaybackSamplesToCopy.  This improves performance
   // by not always trying to process tiny chunks, eating the
   // CPU unnecessarily.
   if (nAvailable < mPlaybackSamplesToCopy)
      return;
 
   // More than mPlaybackSamplesToCopy might be copied:
   // May produce a larger amount when initially priming the buffer, or
   // perhaps again later in play to avoid underfilling the queue and
   // falling behind the real-time demand on the consumer side in the
   // callback.
   auto GetNeeded = [&]() -> size_t {
      // Note that reader might concurrently consume between loop passes below
      // So this might not be nondecreasing
      auto nReady = GetCommonlyWrittenForPlayback();
      return mPlaybackQueueMinimum - std::min(mPlaybackQueueMinimum, nReady);
   };
   auto nNeeded = GetNeeded();
 
   // wxASSERT( nNeeded <= nAvailable );
 
   auto Flush = [&]{
      /* The flushing of all the Puts to the RingBuffers is lifted out of the
      do-loop in ProcessPlaybackSlices, and also after transformation of the
      stream for realtime effects.
 
      It's only here that a release is done on the atomic variable that
      indicates the readiness of sample data to the consumer.  That atomic
      also synchronizes the use of the TimeQueue.
      */
      for (const auto &pBuffer : mPlaybackBuffers)
         pBuffer->Flush();
   };
 
   while (true) {
      // Limit maximum buffer size (increases performance)
      auto available = std::min( nAvailable,
         std::max( nNeeded, mPlaybackSamplesToCopy ) );
 
      // After each loop pass or after break
      Finally Do{ Flush };
 
      if (!ProcessPlaybackSlices(pScope, available))
         // We are not making progress.  May fail to satisfy the minimum but
         // won't loop forever
         break;
 
      // Loop again to satisfy the minimum queue requirement in case there
      // was discarding of processed data for effect latencies
      nNeeded = GetNeeded();
      if (nNeeded == 0)
         break;
 
      // Might increase because the reader consumed some
      nAvailable = GetCommonlyFreePlayback();
   }
}

References GetCommonlyFreePlayback(), AudioIoCallback::GetCommonlyWrittenForPlayback(), min(), AudioIoCallback::mNumPlaybackChannels, AudioIOBase::mOwningProject, AudioIoCallback::mPlaybackBuffers, AudioIoCallback::mPlaybackQueueMinimum, AudioIoCallback::mPlaybackSamplesToCopy, AudioIoCallback::mpTransportState, and ProcessPlaybackSlices().

Referenced by SequenceBufferExchange().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Get()

AudioIO * AudioIO::Get ( )

static

Definition at line 126 of file AudioIO.cpp.

{
   return static_cast< AudioIO* >( AudioIOBase::Get() );
}

References AudioIOBase::Get().

Here is the call graph for this function:

◆ GetBestRate()

double AudioIO::GetBestRate	(	bool	capturing,
		bool	playing,
		double	sampleRate
	)

Return a valid sample rate that is supported by the current I/O device(s).

The return from this function is used to determine the sample rate that audacity actually runs the audio I/O stream at. if there is no suitable rate available from the hardware, it returns 0. The sampleRate argument gives the desired sample rate (the rate of the audio to be handled, i.e. the currently Project Rate). capturing is true if the stream is capturing one or more audio channels, and playing is true if one or more channels are being played.

Definition at line 1701 of file AudioIO.cpp.

{
   // Check if we can use the cached value
   if (mCachedBestRateIn != 0.0 && mCachedBestRateIn == sampleRate
      && mCachedBestRatePlaying == playing && mCachedBestRateCapturing == capturing) {
      return mCachedBestRateOut;
   }
 
   // In order to cache the value, all early returns should instead set retval
   // and jump to finished
   double retval;
 
   std::vector<long> rates;
   if (capturing) wxLogDebug(wxT("AudioIO::GetBestRate() for capture"));
   if (playing) wxLogDebug(wxT("AudioIO::GetBestRate() for playback"));
   wxLogDebug(wxT("GetBestRate() suggested rate %.0lf Hz"), sampleRate);
 
   if (capturing && !playing) {
      rates = GetSupportedCaptureRates(-1, sampleRate);
   }
   else if (playing && !capturing) {
      rates = GetSupportedPlaybackRates(-1, sampleRate);
   }
   else {   // we assume capturing and playing - the alternative would be a
            // bit odd
      rates = GetSupportedSampleRates(-1, -1, sampleRate);
   }
   /* rem rates is the array of hardware-supported sample rates (in the current
    * configuration), sampleRate is the Project Rate (desired sample rate) */
   long rate = (long)sampleRate;
 
   if (make_iterator_range(rates).contains(rate)) {
      wxLogDebug(wxT("GetBestRate() Returning %.0ld Hz"), rate);
      retval = rate;
      goto finished;
      /* the easy case - the suggested rate (project rate) is in the list, and
       * we can just accept that and send back to the caller. This should be
       * the case for most users most of the time (all of the time on
       * Win MME as the OS does resampling) */
   }
 
   /* if we get here, there is a problem - the project rate isn't supported
    * on our hardware, so we can't us it. Need to come up with an alternative
    * rate to use. The process goes like this:
    * * If there are no rates to pick from, we're stuck and return 0 (error)
    * * If there are some rates, we pick the next one higher than the requested
    *   rate to use.
    * * If there aren't any higher, we use the highest available rate */
 
   if (rates.empty()) {
      /* we're stuck - there are no supported rates with this hardware. Error */
      wxLogDebug(wxT("GetBestRate() Error - no supported sample rates"));
      retval = 0.0;
      goto finished;
   }
   int i;
   for (i = 0; i < (int)rates.size(); i++)  // for each supported rate
         {
         if (rates[i] > rate) {
            // supported rate is greater than requested rate
            wxLogDebug(wxT("GetBestRate() Returning next higher rate - %.0ld Hz"), rates[i]);
            retval = rates[i];
            goto finished;
         }
         }
 
   wxLogDebug(wxT("GetBestRate() Returning highest rate - %.0ld Hz"), rates.back());
   retval = rates.back(); // the highest available rate
   goto finished;
 
finished:
   mCachedBestRateIn = sampleRate;
   mCachedBestRateOut = retval;
   mCachedBestRatePlaying = playing;
   mCachedBestRateCapturing = capturing;
   return retval;
}

References AudioIOBase::GetSupportedCaptureRates(), AudioIOBase::GetSupportedPlaybackRates(), AudioIOBase::GetSupportedSampleRates(), make_iterator_range(), AudioIoCallback::mCachedBestRateCapturing, AudioIOBase::mCachedBestRateIn, AudioIoCallback::mCachedBestRateOut, AudioIoCallback::mCachedBestRatePlaying, anonymous_namespace{ClipSegmentTest.cpp}::sampleRate, and wxT().

Referenced by StartPortAudioStream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetCaptureFormat()

sampleFormat AudioIO::GetCaptureFormat ( )

inline

Definition at line 532 of file AudioIO.h.

532{ return mCaptureFormat; }

◆ GetCommonlyAvailCapture()

size_t AudioIO::GetCommonlyAvailCapture ( )

private

Get the number of audio samples ready in all of the recording buffers.

Returns the smallest of the number of samples available for storage in the recording buffers (i.e. the number of samples that can be read from all record buffers without underflow).

Definition at line 1890 of file AudioIO.cpp.

{
   return MinValue(mCaptureBuffers, &RingBuffer::AvailForGet);
}

References RingBuffer::AvailForGet(), AudioIoCallback::mCaptureBuffers, and AudioIoCallback::MinValue().

Referenced by DrainRecordBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetCommonlyFreePlayback()

size_t AudioIO::GetCommonlyFreePlayback ( )

private

Get the number of audio samples free in all of the playback buffers.

Returns the smallest of the buffer free space values in the event that they are different.

Definition at line 1872 of file AudioIO.cpp.

{
   auto commonlyAvail = MinValue(mPlaybackBuffers, &RingBuffer::AvailForPut);
   // MB: subtract a few samples because the code in SequenceBufferExchange has rounding
   // errors
   return commonlyAvail - std::min(size_t(10), commonlyAvail);
}

References RingBuffer::AvailForPut(), min(), AudioIoCallback::MinValue(), and AudioIoCallback::mPlaybackBuffers.

Referenced by FillPlayBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetInputSourceNames()

wxArrayString AudioIO::GetInputSourceNames ( )

Get the list of inputs to the current mixer device.

Returns an array of strings giving the names of the inputs to the soundcard mixer (driven by PortMixer)

Definition at line 432 of file AudioIO.cpp.

{
#if defined(USE_PORTMIXER)
 
   wxArrayString deviceNames;
 
   if( mPortMixer )
   {
      int numSources = Px_GetNumInputSources(mPortMixer);
      for( int source = 0; source < numSources; source++ )
         deviceNames.push_back(wxString(wxSafeConvertMB2WX(Px_GetInputSourceName(mPortMixer, source))));
   }
   else
   {
      wxLogDebug(wxT("AudioIO::GetInputSourceNames(): PortMixer not initialised!"));
   }
 
   return deviceNames;
 
#else
 
   wxArrayString blank;
 
   return blank;
 
#endif
}

References wxT().

Here is the call graph for this function:

◆ GetLastPlaybackTime()

wxLongLong AudioIO::GetLastPlaybackTime ( ) const

inline

Definition at line 501 of file AudioIO.h.

501{ return mLastPlaybackTimeMillis; }

◆ GetMixer()

void AudioIO::GetMixer	(	int *	inputSource,
		float *	inputVolume,
		float *	playbackVolume
	)

Definition at line 400 of file AudioIO.cpp.

{
   *playbackVolume = GetMixerOutputVol();
 
#if defined(USE_PORTMIXER)
 
   PxMixer *mixer = mPortMixer;
 
   if( mixer )
   {
      *recordDevice = Px_GetCurrentInputSource(mixer);
 
      if (mInputMixerWorks)
         *recordVolume = Px_GetInputVolume(mixer);
      else
         *recordVolume = 1.0f;
 
      return;
   }
 
#endif
 
   *recordDevice = 0;
   *recordVolume = 1.0f;
}

References AudioIoCallback::GetMixerOutputVol(), and AudioIOBase::mInputMixerWorks.

Here is the call graph for this function:

◆ GetNumCaptureChannels()

size_t AudioIO::GetNumCaptureChannels ( ) const

inline

Definition at line 534 of file AudioIO.h.

534{ return mNumCaptureChannels; }

◆ GetNumPlaybackChannels()

size_t AudioIO::GetNumPlaybackChannels ( ) const

inline

Definition at line 533 of file AudioIO.h.

533{ return mNumPlaybackChannels; }

◆ GetOwningProject()

std::shared_ptr< AudacityProject > AudioIO::GetOwningProject ( ) const

inline

Definition at line 502 of file AudioIO.h.

503 { return mOwningProject.lock(); }

Referenced by AddState(), RemoveState(), and ReplaceState().

Here is the caller graph for this function:

◆ GetStreamTime()

double AudioIO::GetStreamTime ( )

During playback, the sequence time most recently played.

When playing looped, this will start from t0 again, too. So the returned time should be always between t0 and t1

Definition at line 1779 of file AudioIO.cpp.

{
   // Sequence time readout for the main thread
 
   if( !IsStreamActive() )
      return BAD_STREAM_TIME;
 
   return mPlaybackSchedule.GetSequenceTime();
}

References BAD_STREAM_TIME, PlaybackSchedule::GetSequenceTime(), AudioIOBase::IsStreamActive(), and AudioIoCallback::mPlaybackSchedule.

Here is the call graph for this function:

◆ Init()

void AudioIO::Init ( )

static

Definition at line 190 of file AudioIO.cpp.

{
   auto pAudioIO = safenew AudioIO();
   ugAudioIO.reset(pAudioIO);
   pAudioIO->StartThread();
 
   // Make sure device prefs are initialized
   if (gPrefs->Read(wxT("AudioIO/RecordingDevice"), wxT("")).empty()) {
      int i = getRecordDevIndex();
      const PaDeviceInfo *info = Pa_GetDeviceInfo(i);
      if (info) {
         AudioIORecordingDevice.Write(DeviceName(info));
         AudioIOHost.Write(HostName(info));
      }
   }
 
   if (gPrefs->Read(wxT("AudioIO/PlaybackDevice"), wxT("")).empty()) {
      int i = getPlayDevIndex();
      const PaDeviceInfo *info = Pa_GetDeviceInfo(i);
      if (info) {
         AudioIOPlaybackDevice.Write(DeviceName(info));
         AudioIOHost.Write(HostName(info));
      }
   }
 
   gPrefs->Flush();
}

References AudioIO(), AudioIOHost, AudioIOPlaybackDevice, AudioIORecordingDevice, AudioIOBase::DeviceName(), audacity::BasicSettings::Flush(), AudioIOBase::getPlayDevIndex(), AudioIOBase::getRecordDevIndex(), gPrefs, AudioIOBase::HostName(), audacity::BasicSettings::Read(), safenew, AudioIOBase::ugAudioIO, Setting< T >::Write(), and wxT().

Referenced by AudacityApp::InitPart2().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ InputMixerWorks()

bool AudioIO::InputMixerWorks ( )

Find out if the input hardware level control is available.

Checks the mInputMixerWorks variable, which is set up in AudioIOBase::HandleDeviceChange(). External people care, because we want to disable the UI if it doesn't work.

Definition at line 427 of file AudioIO.cpp.

{
   return mInputMixerWorks;
}

References AudioIOBase::mInputMixerWorks.

◆ IsAvailable()

bool AudioIO::IsAvailable ( AudacityProject & project ) const

Function to automatically set an acceptable volume.

Definition at line 1409 of file AudioIO.cpp.

{
   auto pOwningProject = mOwningProject.lock();
   return !pOwningProject || pOwningProject.get() == &project;
}

References AudioIOBase::mOwningProject, and project.

◆ IsCapturing()

bool AudioIO::IsCapturing ( ) const

Definition at line 3345 of file AudioIO.cpp.

{
   // Includes a test of mTime, used in the main thread
   return IsStreamActive() &&
      GetNumCaptureChannels() > 0 &&
      mPlaybackSchedule.GetSequenceTime() >=
         mPlaybackSchedule.mT0 + mRecordingSchedule.mPreRoll;
}

References PlaybackSchedule::GetSequenceTime(), AudioIOBase::IsStreamActive(), AudioIoCallback::mPlaybackSchedule, RecordingSchedule::mPreRoll, AudioIoCallback::mRecordingSchedule, and PlaybackSchedule::mT0.

Here is the call graph for this function:

◆ LastPaErrorString()

wxString AudioIO::LastPaErrorString ( )

Definition at line 754 of file AudioIO.cpp.

{
   return wxString::Format(wxT("%d %s."), (int) mLastPaError, Pa_GetErrorText(mLastPaError));
}

References AudioIoCallback::mLastPaError, and wxT().

Referenced by StartMonitoring().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ProcessPlaybackSlices()

bool AudioIO::ProcessPlaybackSlices	(	std::optional< RealtimeEffects::ProcessingScope > &	pScope,
		size_t	available
	)

private

Definition at line 1982 of file AudioIO.cpp.

{
   auto &policy = mPlaybackSchedule.GetPolicy();
 
   // msmeyer: When playing a very short selection in looped
   // mode, the selection must be copied to the buffer multiple
   // times, to ensure, that the buffer has a reasonable size
   // This is the purpose of this loop.
   // PRL: or, when scrubbing, we may get work repeatedly from the
   // user interface.
   bool done = false;
   bool progress = false;
   do {
      const auto slice =
         policy.GetPlaybackSlice(mPlaybackSchedule, available);
      const auto &[frames, toProduce] = slice;
      progress = progress || toProduce > 0;
 
      // Update the time queue.  This must be done before writing to the
      // ring buffers of samples, for proper synchronization with the
      // consumer side in the PortAudio thread, which reads the time
      // queue after reading the sample queues.  The sample queues use
      // atomic variables, the time queue doesn't.
      mPlaybackSchedule.mTimeQueue.Producer(mPlaybackSchedule, slice);
 
      // mPlaybackMixers correspond one-to-one with mPlaybackSequences
      size_t iSequence = 0;
      // mPlaybackBuffers correspond many-to-one with mPlaybackSequences
      size_t iBuffer = 0;
      for (auto &mixer : mPlaybackMixers) {
         // The mixer here isn't actually mixing: it's just doing
         // resampling, format conversion, and possibly time track
         // warping
         if (frames > 0) {
            size_t produced = 0;
            if (toProduce)
               produced = mixer->Process(toProduce);
            //wxASSERT(produced <= toProduce);
            // Copy (non-interleaved) mixer outputs to one or more ring buffers
            const auto nChannels = mPlaybackSequences[iSequence++]->NChannels();
            for (size_t j = 0; j < nChannels; ++j) {
               auto warpedSamples = mixer->GetBuffer(j);
               const auto put = mPlaybackBuffers[iBuffer++]->Put(
                  warpedSamples, floatSample, produced, frames - produced);
               // wxASSERT(put == frames);
               // but we can't assert in this thread
               wxUnusedVar(put);
            }
         }
      }
 
      if (mPlaybackSequences.empty())
         // Produce silence in the single ring buffer
         mPlaybackBuffers[0]->Put(nullptr, floatSample, 0, frames);
 
      available -= frames;
      // wxASSERT(available >= 0); // don't assert on this thread
 
      done = policy.RepositionPlayback( mPlaybackSchedule, mPlaybackMixers,
         frames, available );
   } while (available && !done);
 
   // Do any realtime effect processing, more efficiently in at most
   // two buffers per sequence, after all the little slices have been written.
   TransformPlayBuffers(pScope);
   return progress;
}

References floatSample, PlaybackPolicy::GetPlaybackSlice(), PlaybackSchedule::GetPolicy(), AudioIoCallback::mPlaybackBuffers, AudioIoCallback::mPlaybackMixers, AudioIoCallback::mPlaybackSchedule, AudioIoCallback::mPlaybackSequences, PlaybackSchedule::mTimeQueue, PlaybackSchedule::TimeQueue::Producer(), and TransformPlayBuffers().

Referenced by FillPlayBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RemoveState()

void AudioIO::RemoveState	(	AudacityProject &	project,
		ChannelGroup *	pGroup,
		std::shared_ptr< RealtimeEffectState >	pState
	)

Forwards to RealtimeEffectManager::RemoveState with proper init scope.

Definition at line 369 of file AudioIO.cpp.

{
   RealtimeEffects::InitializationScope *pInit = nullptr;
   if (mpTransportState && mpTransportState->mpRealtimeInitialization)
      if (auto pProject = GetOwningProject(); pProject.get() == &project)
         pInit = &*mpTransportState->mpRealtimeInitialization;
   RealtimeEffectManager::Get(project).RemoveState(pInit, pGroup, pState);
}

References RealtimeEffectManager::Get(), GetOwningProject(), AudioIoCallback::mpTransportState, project, and RealtimeEffectManager::RemoveState().

Referenced by EffectUIHost::CleanupRealtime(), and anonymous_namespace{RealtimeEffectPanel.cpp}::RealtimeEffectControl::RemoveFromList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ReplaceState()

std::shared_ptr< RealtimeEffectState > AudioIO::ReplaceState	(	AudacityProject &	project,
		ChannelGroup *	pGroup,
		size_t	index,
		const PluginID &	id
	)

Forwards to RealtimeEffectManager::ReplaceState with proper init scope.

Postcondition: result: !result || result->GetEffect() != nullptr

Definition at line 358 of file AudioIO.cpp.

{
   RealtimeEffects::InitializationScope *pInit = nullptr;
   if (mpTransportState && mpTransportState->mpRealtimeInitialization)
      if (auto pProject = GetOwningProject(); pProject.get() == &project)
         pInit = &*mpTransportState->mpRealtimeInitialization;
   return RealtimeEffectManager::Get(project)
      .ReplaceState(pInit, pGroup, index, id);
}

References RealtimeEffectManager::Get(), GetOwningProject(), AudioIoCallback::mpTransportState, project, and RealtimeEffectManager::ReplaceState().

Here is the call graph for this function:

◆ ResetOwningProject()

void AudioIO::ResetOwningProject ( )

private

Definition at line 770 of file AudioIO.cpp.

{
   mOwningProject.reset();
}

References AudioIOBase::mOwningProject.

Referenced by SetOwningProject(), StartPortAudioStream(), StopStream(), and ~AudioIO().

Here is the caller graph for this function:

◆ SeekStream()

void AudioIO::SeekStream ( double seconds )

inline

Move the playback / recording position of the current stream by the specified amount from where it is now.

Definition at line 490 of file AudioIO.h.

490{ mSeek = seconds; }

AudioIoCallback::mSeek

double mSeek

Definition: AudioIO.h:293

◆ SequenceBufferExchange()

void AudioIO::SequenceBufferExchange ( )

private

Called in a loop from another worker thread that does not have the low-latency constraints of the PortAudio callback thread. Does less frequent and larger batches of work that may include memory allocations and database operations. RingBuffer objects mediate the transfer between threads, to overcome the mismatch of their batch sizes.

Definition at line 1898 of file AudioIO.cpp.

{
   FillPlayBuffers();
   DrainRecordBuffers();
}

References DrainRecordBuffers(), and FillPlayBuffers().

Referenced by AudioThread().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetMeters()

void AudioIO::SetMeters ( )

private

Set the current VU meters - this should be done once after each call to StartStream currently.

Definition at line 1415 of file AudioIO.cpp.

{
   if (auto pInputMeter = mInputMeter.lock())
      pInputMeter->Reset(mRate, true);
   if (auto pOutputMeter = mOutputMeter.lock())
      pOutputMeter->Reset(mRate, true);
}

References AudioIOBase::mInputMeter, AudioIOBase::mOutputMeter, and AudioIOBase::mRate.

Referenced by StartPortAudioStream().

Here is the caller graph for this function:

◆ SetMixer()

void AudioIO::SetMixer	(	int	inputSource,
		float	inputVolume,
		float	playbackVolume
	)

Definition at line 380 of file AudioIO.cpp.

{
   SetMixerOutputVol(playbackVolume);
   AudioIOPlaybackVolume.Write(playbackVolume);
 
#if defined(USE_PORTMIXER)
   PxMixer *mixer = mPortMixer;
   if( !mixer )
      return;
 
   float oldRecordVolume = Px_GetInputVolume(mixer);
 
   AudioIoCallback::SetMixer(inputSource);
   if( oldRecordVolume != recordVolume )
      Px_SetInputVolume(mixer, recordVolume);
 
#endif
}

References AudioIOPlaybackVolume, AudioIOBase::SetMixer(), AudioIoCallback::SetMixerOutputVol(), and Setting< T >::Write().

Here is the call graph for this function:

◆ SetOwningProject()

void AudioIO::SetOwningProject ( const std::shared_ptr< AudacityProject > & pProject )

private

Definition at line 759 of file AudioIO.cpp.

{
   if ( !mOwningProject.expired() ) {
      wxASSERT(false);
      ResetOwningProject();
   }
 
   mOwningProject = pProject;
}

References AudioIOBase::mOwningProject, and ResetOwningProject().

Referenced by StartPortAudioStream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetPaused()

void AudioIO::SetPaused ( bool state )

Pause and un-pause playback and recording.

Definition at line 1686 of file AudioIO.cpp.

{
   if (state != IsPaused())
   {
      if (auto pOwningProject = mOwningProject.lock()) {
         // The realtime effects manager may remain "active" but becomes
         // "suspended" or "resumed".
         auto &em = RealtimeEffectManager::Get(*pOwningProject);
         em.SetSuspended(state);
      }
   }
 
   mPaused.store(state, std::memory_order_relaxed);
}

References RealtimeEffectManager::Get(), AudioIOBase::IsPaused(), AudioIOBase::mOwningProject, and AudioIOBase::mPaused.

Here is the call graph for this function:

◆ StartMonitoring()

void AudioIO::StartMonitoring ( const AudioIOStartStreamOptions & options )

Start up Portaudio for capture and recording as needed for input monitoring and software playthrough only.

This uses the Default project sample format, current sample rate, and selected number of input channels to open the recording device and start reading input data. If software playthrough is enabled, it also opens the output device in stereo to play the data through

Definition at line 775 of file AudioIO.cpp.

{
   if ( mPortStreamV19 || mStreamToken )
      return;
 
   bool success;
   auto captureFormat = QualitySettings::SampleFormatChoice();
   auto captureChannels = AudioIORecordChannels.Read();
   gPrefs->Read(wxT("/AudioIO/SWPlaythrough"), &mSoftwarePlaythrough, false);
   int playbackChannels = 0;
 
   if (mSoftwarePlaythrough)
      playbackChannels = 2;
 
   // FIXME: TRAP_ERR StartPortAudioStream (a PaError may be present)
   // but StartPortAudioStream function only returns true or false.
   mUsingAlsa = false;
   mCaptureFormat = captureFormat;
   mCaptureRate = 44100.0; // Shouldn't matter
   success = StartPortAudioStream(options,
      static_cast<unsigned int>(playbackChannels),
      static_cast<unsigned int>(captureChannels));
 
   auto pOwningProject = mOwningProject.lock();
   if (!success) {
      using namespace BasicUI;
      auto msg = XO("Error opening recording device.\nError code: %s")
         .Format( Get()->LastPaErrorString() );
      ShowErrorDialog( *ProjectFramePlacement( pOwningProject.get() ),
         XO("Error"), msg, wxT("Error_opening_sound_device"),
         ErrorDialogOptions{ ErrorDialogType::ModalErrorReport } );
      return;
   }
 
   Publish({ pOwningProject.get(), AudioIOEvent::MONITOR, true });
 
   // FIXME: TRAP_ERR PaErrorCode 'noted' but not reported in StartMonitoring.
   // Now start the PortAudio stream!
   // TODO: ? Factor out and reuse error reporting code from end of
   // AudioIO::StartStream?
   mLastPaError = Pa_StartStream( mPortStreamV19 );
 
   // Update UI display only now, after all possibilities for error are past.
   auto pListener = GetListener();
   if ((mLastPaError == paNoError) && pListener) {
      // advertise the chosen I/O sample rate to the UI
      pListener->OnAudioIORate((int)mRate);
   }
}

References AudioIORecordChannels, Get(), AudioIoCallback::GetListener(), gPrefs, LastPaErrorString(), AudioIoCallback::mCaptureFormat, AudioIoCallback::mCaptureRate, AudioIoCallback::mLastPaError, AudioIOEvent::MONITOR, AudioIOBase::mOwningProject, AudioIOBase::mPortStreamV19, AudioIOBase::mRate, AudioIoCallback::mSoftwarePlaythrough, AudioIOBase::mStreamToken, AudioIoCallback::mUsingAlsa, ProjectFramePlacement(), Observer::Publisher< AudioIOEvent >::Publish(), audacity::BasicSettings::Read(), Setting< T >::Read(), QualitySettings::SampleFormatChoice(), BasicUI::ShowErrorDialog(), StartPortAudioStream(), wxT(), and XO().

Here is the call graph for this function:

◆ StartPortAudioStream()

bool AudioIO::StartPortAudioStream	(	const AudioIOStartStreamOptions &	options,
		unsigned int	numPlaybackChannels,
		unsigned int	numCaptureChannels
	)

private

Opens the portaudio stream(s) used to do playback or recording (or both) through.

The sampleRate passed is the Project Rate of the active project. It may or may not be actually supported by playback or recording hardware currently in use (for many reasons). The number of Capture and Playback channels requested includes an allocation for doing software playthrough if necessary. The captureFormat is used for recording only, the playback being floating point always. Returns true if the stream opened successfully and false if it did not.

Definition at line 473 of file AudioIO.cpp.

{
   auto sampleRate = options.rate;
   mNumPauseFrames = 0;
   SetOwningProject( options.pProject );
   bool success = false;
   auto cleanup = finally([&]{
      if (!success)
         ResetOwningProject();
   });
 
   // PRL:  Protection from crash reported by David Bailes, involving starting
   // and stopping with frequent changes of active window, hard to reproduce
   if (mOwningProject.expired())
      return false;
 
   mInputMeter.reset();
   mOutputMeter.reset();
 
   mLastPaError = paNoError;
   // pick a rate to do the audio I/O at, from those available. The project
   // rate is suggested, but we may get something else if it isn't supported
   mRate = GetBestRate(numCaptureChannels > 0, numPlaybackChannels > 0, sampleRate);
 
   // GetBestRate() will return 0.0 for bidirectional streams when there is no
   // common sample rate supported by both the input and output devices.
   // Bidirectional streams are used when recording while overdub or
   // software playthrough options are enabled.
 
   // Pa_OpenStream() will return paInvalidSampleRate when trying to create the
   // bidirectional stream with a sampleRate of 0.0
   bool isStreamBidirectional = (numCaptureChannels > 0) && (numPlaybackChannels > 0);
   bool isUnsupportedSampleRate = isStreamBidirectional && (mRate == 0.0);
 
   // July 2016 (Carsten and Uwe)
   // BUG 193: Tell PortAudio sound card will handle 24 bit (under DirectSound) using
   // userData.
   auto captureFormat = mCaptureFormat;
   auto captureFormat_saved = captureFormat;
   // Special case: Our 24-bit sample format is different from PortAudio's
   // 3-byte packed format. So just make PortAudio return float samples,
   // since we need float values anyway to apply the gain.
   // ANSWER-ME: So we *never* actually handle 24-bit?! This causes mCapture to
   // be set to floatSample below.
   // JKC: YES that's right.  Internally Audacity uses float, and float has space for
   // 24 bits as well as exponent.  Actual 24 bit would require packing and
   // unpacking unaligned bytes and would be inefficient.
   // ANSWER ME: is floatSample 64 bit on 64 bit machines?
   if (captureFormat == int24Sample)
   {
      captureFormat = floatSample;
      // mCaptureFormat is overwritten before the call to
      // StartPortAudioStream. So the hack with captureFormat_saved is
      // still working (assuming it worked before).
      mCaptureFormat = captureFormat;
   }
 
   mNumPlaybackChannels = numPlaybackChannels;
   mNumCaptureChannels = numCaptureChannels;
 
   bool usePlayback = false, useCapture = false;
   PaStreamParameters playbackParameters{};
   PaStreamParameters captureParameters{};
 
   #ifdef __WXMSW__
   PaWasapiStreamInfo wasapiStreamInfo{};
   #endif
 
   auto latencyDuration = AudioIOLatencyDuration.Read();
 
   if( numPlaybackChannels > 0)
   {
      usePlayback = true;
 
      // this sets the device index to whatever is "right" based on preferences,
      // then defaults
      playbackParameters.device = getPlayDevIndex();
 
      const PaDeviceInfo *playbackDeviceInfo;
      playbackDeviceInfo = Pa_GetDeviceInfo( playbackParameters.device );
 
      if( playbackDeviceInfo == NULL )
         return false;
 
      // regardless of source formats, we always mix to float
      playbackParameters.sampleFormat = paFloat32;
      playbackParameters.hostApiSpecificStreamInfo = NULL;
      playbackParameters.channelCount = mNumPlaybackChannels;
 
      const PaHostApiInfo* hostInfo = Pa_GetHostApiInfo(playbackDeviceInfo->hostApi);
      bool isWASAPI = (hostInfo && hostInfo->type == paWASAPI);
 
      #ifdef __WXMSW__
      // If the host API is WASAPI, the stream is bidirectional and there is no
      // supported sample rate enable the WASAPI Sample Rate Conversion
      // for the playback device.
      if (isWASAPI && isUnsupportedSampleRate)
      {
         wasapiStreamInfo.size = sizeof(PaWasapiStreamInfo);
         wasapiStreamInfo.hostApiType = paWASAPI;
         wasapiStreamInfo.version = 1;
         wasapiStreamInfo.flags = paWinWasapiAutoConvert;
 
         playbackParameters.hostApiSpecificStreamInfo = &wasapiStreamInfo;
      }
      #endif
 
      if (mSoftwarePlaythrough)
         playbackParameters.suggestedLatency =
            playbackDeviceInfo->defaultLowOutputLatency;
      else {
         // When using WASAPI, the suggested latency does not affect
         // the latency of the playback, but the position of playback is given as if
         // there was the suggested latency. This results in the last "suggested latency"
         // of a selection not being played. So for WASAPI use 0.0 for the suggested
         // latency regardless of user setting. See bug 1949.
         playbackParameters.suggestedLatency = isWASAPI ? 0.0 : latencyDuration/1000.0;
      }
 
      mOutputMeter = options.playbackMeter;
   }
 
   if( numCaptureChannels > 0)
   {
      useCapture = true;
 
      const PaDeviceInfo *captureDeviceInfo;
      // retrieve the index of the device set in the prefs, or a sensible
      // default if it isn't set/valid
      captureParameters.device = getRecordDevIndex();
 
      captureDeviceInfo = Pa_GetDeviceInfo( captureParameters.device );
 
      if( captureDeviceInfo == NULL )
         return false;
 
      const PaHostApiInfo* hostInfo = Pa_GetHostApiInfo(captureDeviceInfo->hostApi);
      bool isWASAPI = (hostInfo && hostInfo->type == paWASAPI);
 
      // If the stream is bidirectional and there is no supported sample rate
      // set mRate to the value supported by the capture device.
      if (isWASAPI && isUnsupportedSampleRate)
         mRate = captureDeviceInfo->defaultSampleRate;
 
      captureParameters.sampleFormat =
         AudacityToPortAudioSampleFormat(mCaptureFormat);
 
      captureParameters.hostApiSpecificStreamInfo = NULL;
      captureParameters.channelCount = mNumCaptureChannels;
 
      if (mSoftwarePlaythrough)
         captureParameters.suggestedLatency =
            captureDeviceInfo->defaultHighInputLatency;
      else
         captureParameters.suggestedLatency = latencyDuration/1000.0;
 
      SetCaptureMeter( mOwningProject.lock(), options.captureMeter );
   }
 
   const auto deviceInfo = usePlayback ?
                              Pa_GetDeviceInfo(playbackParameters.device) :
                              Pa_GetDeviceInfo(captureParameters.device);
 
   if (deviceInfo != nullptr)
   {
      const auto hostApiInfo = Pa_GetHostApiInfo(deviceInfo->hostApi);
 
      if (hostApiInfo)
      {
         mUsingAlsa = hostApiInfo->type == paALSA;
         mUsingJack = hostApiInfo->type == paJACK;
      }
   }
 
   SetMeters();
 
#ifdef USE_PORTMIXER
#ifdef __WXMSW__
   //mchinen nov 30 2010.  For some reason Pa_OpenStream resets the input volume on windows.
   //so cache and restore after it.
   //The actual problem is likely in portaudio's pa_win_wmme.c OpenStream().
   float oldRecordVolume = Px_GetInputVolume(mPortMixer);
#endif
#endif
 
   // July 2016 (Carsten and Uwe)
   // BUG 193: Possibly tell portAudio to use 24 bit with DirectSound.
   int  userData = 24;
   int* lpUserData = (captureFormat_saved == int24Sample) ? &userData : NULL;
 
   // (Linux, bug 1885) After scanning devices it takes a little time for the
   // ALSA device to be available, so allow retries.
   // On my test machine, no more than 3 attempts are required.
   unsigned int maxTries = 1;
#ifdef __WXGTK__
   {
      using namespace std::chrono;
      if (DeviceManager::Instance()->GetTimeSinceRescan() < 10s)
         maxTries = 5;
   }
#endif
 
   for (unsigned int tries = 0; tries < maxTries; tries++) {
      mLastPaError = Pa_OpenStream( &mPortStreamV19,
                                    useCapture ? &captureParameters : NULL,
                                    usePlayback ? &playbackParameters : NULL,
                                    mRate, paFramesPerBufferUnspecified,
                                    paNoFlag,
                                    audacityAudioCallback, lpUserData );
      if (mLastPaError == paNoError) {
         const auto stream = Pa_GetStreamInfo(mPortStreamV19);
         // Use the reported latency as a hint about the hardware buffer size
         // required for uninterrupted playback.
         const auto outputLatency =
            mUsingJack ?
               // When using Jack as a host, PA calculates the wrong latency
               // if a non system port is used. Assume, that Jack provides a very
               // low latency, lower than user requested
               // (https://github.com/audacity/audacity/issues/4646)
               (latencyDuration / 1000.0) :
               // Otherwise, use the (likely incorrect) latency reported by PA
               stream->outputLatency;
 
         mHardwarePlaybackLatencyFrames = lrint(outputLatency * mRate);
#ifdef __WXGTK__
         // DV: When using ALSA PortAudio does not report the buffer size.
         // Instead, it reports periodSize * (periodsCount - 1). It is impossible
         // to retrieve periodSize or periodsCount either. By default PA sets
         // periodsCount to 4. However it was observed, that PA reports back ~100msec
         // latency and expects a buffer of ~200msecs on Audacity default settings
         // which suggests that ALSA changes the periodsCount to suit its needs.
         //
         // Why 3? 2 doesn't work for me, 3 does :-) So similar to PA - this
         // is the value that works for author setup.
         if (mUsingAlsa)
            mHardwarePlaybackLatencyFrames *= 3;
#endif
         break;
      }
      wxLogDebug("Attempt %u to open capture stream failed with: %d", 1 + tries, mLastPaError);
      using namespace std::chrono;
      std::this_thread::sleep_for(1s);
   }
 
 
#if USE_PORTMIXER
#ifdef __WXMSW__
   Px_SetInputVolume(mPortMixer, oldRecordVolume);
#endif
   if (mPortStreamV19 != NULL && mLastPaError == paNoError) {
 
      #ifdef __WXMAC__
      if (mPortMixer) {
         if (Px_SupportsPlaythrough(mPortMixer)) {
            bool playthrough = false;
 
            mPreviousHWPlaythrough = Px_GetPlaythrough(mPortMixer);
 
            // Bug 388.  Feature not supported.
            //gPrefs->Read(wxT("/AudioIO/Playthrough"), &playthrough, false);
            if (playthrough)
               Px_SetPlaythrough(mPortMixer, 1.0);
            else
               Px_SetPlaythrough(mPortMixer, 0.0);
         }
      }
      #endif
   }
#endif
 
#if (defined(__WXMAC__) || defined(__WXMSW__)) && wxCHECK_VERSION(3,1,0)
   // Don't want the system to sleep while audio I/O is active
   if (mPortStreamV19 != NULL && mLastPaError == paNoError) {
      wxPowerResource::Acquire(wxPOWER_RESOURCE_SCREEN, _("Audacity Audio"));
   }
#endif
 
   return (success = (mLastPaError == paNoError));
}

Referenced by StartMonitoring(), and StartStream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ StartStream()

int AudioIO::StartStream	(	const TransportSequences &	sequences,
		double	t0,
		double	t1,
		double	mixerLimit,
		const AudioIOStartStreamOptions &	options
	)

Start recording or playing back audio.

Allocates buffers for recording and playback, gets the Audio thread to fill them, and sets the stream rolling. If successful, returns a token identifying this particular stream instance. For use with IsStreamActive()

Precondition: p && p->FindChannelGroup() for all pointers p in sequences.playbackSequences; p != nullptr for all pointers p in sequences.captureSequences

Parameters

mixerLimit Time at which mixer stops producing, maybe > t1

Definition at line 825 of file AudioIO.cpp.

{
   // precondition
   assert(std::all_of(
      sequences.playbackSequences.begin(), sequences.playbackSequences.end(),
      [](const auto &pSequence){
         const auto pGroup =
            pSequence ? pSequence->FindChannelGroup() : nullptr;
         return pGroup; }
   ));
 
   const auto &pStartTime = options.pStartTime;
   t1 = std::min(t1, mixerLimit);
 
   mLostSamples = 0;
   mLostCaptureIntervals.clear();
   mDetectDropouts =
      gPrefs->Read( WarningDialogKey(wxT("DropoutDetected")), true ) != 0;
   auto cleanup = finally ( [this] { ClearRecordingException(); } );
 
   if( IsBusy() )
      return 0;
 
   // We just want to set mStreamToken to -1 - this way avoids
   // an extremely rare but possible race condition, if two functions
   // somehow called StartStream at the same time...
   mStreamToken--;
   if (mStreamToken != -1)
      return 0;
 
   // TODO: we don't really need to close and reopen stream if the
   // format matches; however it's kind of tricky to keep it open...
   //
   //   if (sampleRate == mRate &&
   //       playbackChannels == mNumPlaybackChannels &&
   //       captureChannels == mNumCaptureChannels &&
   //       captureFormat == mCaptureFormat) {
 
   if (mPortStreamV19) {
      StopStream();
      while(mPortStreamV19) {
         using namespace std::chrono;
         std::this_thread::sleep_for(50ms);
      }
   }
 
   gPrefs->Read(wxT("/AudioIO/SWPlaythrough"), &mSoftwarePlaythrough, false);
   mPauseRec = SoundActivatedRecord.Read();
   gPrefs->Read(wxT("/AudioIO/Microfades"), &mbMicroFades, false);
   int silenceLevelDB;
   gPrefs->Read(wxT("/AudioIO/SilenceLevel"), &silenceLevelDB, -50);
   int dBRange = DecibelScaleCutoff.Read();
   if(silenceLevelDB < -dBRange)
   {
      silenceLevelDB = -dBRange + 3;
      // meter range was made smaller than SilenceLevel
      // so set SilenceLevel reasonable
 
      // PRL:  update prefs, or correct it only in-session?
      // The behavior (as of 2.3.1) was the latter, the code suggested that
      // the intent was the former;  I preserve the behavior, but uncomment
      // this if you disagree.
      // gPrefs->Write(wxT("/AudioIO/SilenceLevel"), silenceLevelDB);
      // gPrefs->Flush();
   }
   mSilenceLevel = DB_TO_LINEAR(silenceLevelDB);  // meter goes -dBRange dB -> 0dB
 
   // Clamp pre-roll so we don't play before time 0
   const auto preRoll = std::max(0.0, std::min(t0, options.preRoll));
   mRecordingSchedule = {};
   mRecordingSchedule.mPreRoll = preRoll;
   mRecordingSchedule.mLatencyCorrection =
      AudioIOLatencyCorrection.Read() / 1000.0;
   mRecordingSchedule.mDuration = t1 - t0;
   if (options.pCrossfadeData)
      mRecordingSchedule.mCrossfadeData.swap( *options.pCrossfadeData );
 
   mListener = options.listener;
   mRate    = options.rate;
 
   mSeek    = 0;
   mLastRecordingOffset = 0;
   mCaptureSequences = sequences.captureSequences;
   mPlaybackSequences = sequences.playbackSequences;
 
   bool commit = false;
   auto cleanupSequences = finally([&]{
      if (!commit) {
         // Don't keep unnecessary shared pointers to sequences
         mPlaybackSequences.clear();
         mCaptureSequences.clear();
         for(auto &ext : Extensions())
            ext.AbortOtherStream();
 
         // Don't cause a busy wait in the audio thread after stopping scrubbing
         mPlaybackSchedule.ResetMode();
      }
   });
 
   mPlaybackBuffers.clear();
   mScratchBuffers.clear();
   mScratchPointers.clear();
   mPlaybackMixers.clear();
   mCaptureBuffers.clear();
   mResample.clear();
   mPlaybackSchedule.mTimeQueue.Clear();
 
   mPlaybackSchedule.Init(
      t0, t1, options, mCaptureSequences.empty() ? nullptr : &mRecordingSchedule );
 
   unsigned int playbackChannels = 0;
   size_t numCaptureChannels = 0;
   sampleFormat captureFormat = floatSample;
   double captureRate = 44100.0;
 
   auto pListener = GetListener();
 
   if (sequences.playbackSequences.size() > 0
      || sequences.otherPlayableSequences.size() > 0)
      playbackChannels = 2;
 
   if (mSoftwarePlaythrough)
      playbackChannels = 2;
 
   if (mCaptureSequences.size() > 0) {
      numCaptureChannels = accumulate(
         mCaptureSequences.begin(), mCaptureSequences.end(), size_t{},
         [](auto acc, const auto &pSequence) {
            return acc + pSequence->NChannels();
         });
      // I don't deal with the possibility of the capture sequences
      // having different sample formats, since it will never happen
      // with the current code.  This code wouldn't *break* if this
      // assumption was false, but it would be sub-optimal.  For example,
      // if the first sequence was 16-bit and the second sequence was 24-bit,
      // we would set the sound card to capture in 16 bits and the second
      // sequence wouldn't get the benefit of all 24 bits the card is capable
      // of.
      const auto &sequence0 = mCaptureSequences[0];
      captureFormat = sequence0->GetSampleFormat();
      captureRate = sequence0->GetRate();
 
      // Tell project that we are about to start recording
      if (pListener)
         pListener->OnAudioIOStartRecording();
   }
 
   bool successAudio;
 
   mCaptureFormat = captureFormat;
   mCaptureRate = captureRate;
   successAudio =
      StartPortAudioStream(options, playbackChannels, numCaptureChannels);
 
   // Call this only after reassignment of mRate that might happen in the
   // previous call.
   mPlaybackSchedule.GetPolicy().Initialize( mPlaybackSchedule, mRate );
 
   auto range = Extensions();
   successAudio = successAudio &&
      std::all_of(range.begin(), range.end(),
         [this, &sequences, t0](auto &ext){
            return ext.StartOtherStream(sequences,
              (mPortStreamV19 != NULL && mLastPaError == paNoError)
                 ? Pa_GetStreamInfo(mPortStreamV19) : nullptr,
              t0, mRate ); });
 
   if (!successAudio) {
      if (pListener && numCaptureChannels > 0)
         pListener->OnAudioIOStopRecording();
      mStreamToken = 0;
 
      return 0;
   }
 
   {
      double mixerStart = t0;
      if (pStartTime)
         mixerStart = std::min( mixerStart, *pStartTime );
      if (!AllocateBuffers(options, sequences,
         mixerStart, mixerLimit, options.rate))
         return 0;
   }
 
   mpTransportState = std::make_unique<TransportState>(mOwningProject,
      mPlaybackSequences, mNumPlaybackChannels, mRate);
 
#ifdef EXPERIMENTAL_AUTOMATED_INPUT_LEVEL_ADJUSTMENT
   AILASetStartTime();
#endif
 
   if (pStartTime)
   {
      // Calculate the NEW time position
      const auto time = *pStartTime;
 
      // Main thread's initialization of mTime
      mPlaybackSchedule.SetSequenceTime( time );
      mPlaybackSchedule.GetPolicy().OffsetSequenceTime( mPlaybackSchedule, 0 );
 
      // Reset mixer positions for all playback sequences
      for (auto &mixer : mPlaybackMixers)
         mixer->Reposition( time );
   }
 
   // Now that we are done with AllocateBuffers() and SetSequenceTime():
   mPlaybackSchedule.mTimeQueue.Prime(mPlaybackSchedule.GetSequenceTime());
   // else recording only without overdub
 
   // We signal the audio thread to call SequenceBufferExchange, to prime the RingBuffers
   // so that they will have data in them when the stream starts.  Having the
   // audio thread call SequenceBufferExchange here makes the code more predictable, since
   // SequenceBufferExchange will ALWAYS get called from the Audio thread.
   mAudioThreadShouldCallSequenceBufferExchangeOnce
      .store(true, std::memory_order_release);
 
   while( mAudioThreadShouldCallSequenceBufferExchangeOnce
      .load(std::memory_order_acquire)) {
      using namespace std::chrono;
      auto interval = 50ms;
      if (options.playbackStreamPrimer) {
         interval = options.playbackStreamPrimer();
      }
      std::this_thread::sleep_for(interval);
   }
 
   if(mNumPlaybackChannels > 0 || mNumCaptureChannels > 0) {
 
#ifdef REALTIME_ALSA_THREAD
      // PRL: Do this in hope of less thread scheduling jitter in calls to
      // audacityAudioCallback.
      // Not needed to make audio playback work smoothly.
      // But needed in case we also play MIDI, so that the variable "offset"
      // in AudioIO::MidiTime() is a better approximation of the duration
      // between the call of audacityAudioCallback and the actual output of
      // the first audio sample.
      // (Which we should be able to determine from fields of
      // PaStreamCallbackTimeInfo, but that seems not to work as documented with
      // ALSA.)
      if (mUsingAlsa)
         // Perhaps we should do this only if also playing MIDI ?
         PaAlsa_EnableRealtimeScheduling( mPortStreamV19, 1 );
#endif
 
      //
      // Generate a unique value each time, to be returned to
      // clients accessing the AudioIO API, so they can query if they
      // are the ones who have reserved AudioIO or not.
      //
      // It is important to set this before setting the portaudio stream in
      // motion -- otherwise it may play an unspecified number of leading
      // zeroes.
      mStreamToken = (++mNextStreamToken);
 
      // This affects AudioThread (not the portaudio callback).
      // Probably not needed so urgently before portaudio thread start for usual
      // playback, since our ring buffers have been primed already with 4 sec
      // of audio, but then we might be scrubbing, so do it.
      StartAudioThread();
 
      mForceFadeOut.store(false, std::memory_order_relaxed);
 
      // Now start the PortAudio stream!
      PaError err;
      err = Pa_StartStream( mPortStreamV19 );
 
      if( err != paNoError )
      {
         mStreamToken = 0;
 
         StopAudioThread();
 
         if (pListener && mNumCaptureChannels > 0)
            pListener->OnAudioIOStopRecording();
         StartStreamCleanup();
         // PRL: PortAudio error messages are sadly not internationalized
         BasicUI::ShowMessageBox(
            Verbatim( LAT1CTOWX(Pa_GetErrorText(err)) ) );
         return 0;
      }
   }
 
   // Update UI display only now, after all possibilities for error are past.
   if (pListener) {
      // advertise the chosen I/O sample rate to the UI
      pListener->OnAudioIORate((int)mRate);
   }
 
   auto pOwningProject = mOwningProject.lock();
   if (mNumPlaybackChannels > 0)
      Publish({ pOwningProject.get(), AudioIOEvent::PLAYBACK, true });
   if (mNumCaptureChannels > 0)
      Publish({ pOwningProject.get(), AudioIOEvent::CAPTURE, true });
 
   commit = true;
 
   WaitForAudioThreadStarted();
 
   return mStreamToken;
}

Here is the call graph for this function:

◆ StartStreamCleanup()

void AudioIO::StartStreamCleanup ( bool bOnlyBuffers = false )

private

Clean up after StartStream if it fails.

If bOnlyBuffers is specified, it only cleans up the buffers.

Definition at line 1386 of file AudioIO.cpp.

{
   mpTransportState.reset();
 
   mPlaybackBuffers.clear();
   mScratchBuffers.clear();
   mScratchPointers.clear();
   mPlaybackMixers.clear();
   mCaptureBuffers.clear();
   mResample.clear();
   mPlaybackSchedule.mTimeQueue.Clear();
 
   if(!bOnlyBuffers)
   {
      Pa_AbortStream( mPortStreamV19 );
      Pa_CloseStream( mPortStreamV19 );
      mPortStreamV19 = NULL;
      mStreamToken = 0;
   }
 
   mPlaybackSchedule.GetPolicy().Finalize( mPlaybackSchedule );
}

References PlaybackSchedule::TimeQueue::Clear(), PlaybackPolicy::Finalize(), PlaybackSchedule::GetPolicy(), AudioIoCallback::mCaptureBuffers, AudioIoCallback::mPlaybackBuffers, AudioIoCallback::mPlaybackMixers, AudioIoCallback::mPlaybackSchedule, AudioIOBase::mPortStreamV19, AudioIoCallback::mpTransportState, AudioIoCallback::mResample, AudioIoCallback::mScratchBuffers, AudioIoCallback::mScratchPointers, AudioIOBase::mStreamToken, and PlaybackSchedule::mTimeQueue.

Referenced by AllocateBuffers(), and StartStream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ StartThread()

void AudioIO::StartThread ( )

private

Definition at line 309 of file AudioIO.cpp.

{
   mAudioThread = std::thread(AudioThread, ref(mFinishAudioThread));
}

References AudioThread(), AudioIoCallback::mAudioThread, and AudioIoCallback::mFinishAudioThread.

Here is the call graph for this function:

◆ StopStream()

void AudioIO::StopStream ( )

overridevirtual

Stop recording, playback or input monitoring.

Does quite a bit of housekeeping, including switching off monitoring, flushing recording buffers out to RecordableSequences, and applies latency correction to recorded sequences if necessary

Implements AudioIOBase.

Definition at line 1423 of file AudioIO.cpp.

{
   auto cleanup = finally ( [this] {
      ClearRecordingException();
      mRecordingSchedule.mCrossfadeData.clear(); // free arrays
   } );
 
   if( mPortStreamV19 == NULL )
      return;
 
   // DV: This code seems to be unnecessary.
   // We do not leave mPortStreamV19 open in stopped
   // state. (Do we?)
   // This breaks WASAPI backend, as it sets the `running`
   // flag to `false` asynchronously.
   // Previously we have patched PortAudio and the patch
   // was breaking IsStreamStopped() == !IsStreamActive()
   // invariant.
   /*
   if ( Pa_IsStreamStopped(mPortStreamV19) )
      return;
   */
 
#if (defined(__WXMAC__) || defined(__WXMSW__)) && wxCHECK_VERSION(3,1,0)
   // Re-enable system sleep
   wxPowerResource::Release(wxPOWER_RESOURCE_SCREEN);
#endif
 
   if( mAudioThreadSequenceBufferExchangeLoopRunning
      .load(std::memory_order_relaxed) )
   {
      // PortAudio callback can use the information that we are stopping to fade
      // out the audio.  Give PortAudio callback a chance to do so.
      mForceFadeOut.store(true, std::memory_order_relaxed);
      auto latency = static_cast<long>(AudioIOLatencyDuration.Read());
      // If we can gracefully fade out in 200ms, with the faded-out play buffers making it through
      // the sound card, then do so.  If we can't, don't wait around.  Just stop quickly and accept
      // there will be a click.
      if( mbMicroFades  && (latency < 150 )) {
         using namespace std::chrono;
         std::this_thread::sleep_for(milliseconds{latency + 50});
      }
   }
 
   wxMutexLocker locker(mSuspendAudioThread);
 
   //
   // We got here in one of two ways:
   //
   // 1. The user clicked the stop button and we therefore want to stop
   //    as quickly as possible.  So we use AbortStream().  If this is
   //    the case the portaudio stream is still in the Running state
   //    (see PortAudio state machine docs).
   //
   // 2. The callback told PortAudio to stop the stream since it had
   //    reached the end of the selection.  The UI thread discovered
   //    this by noticing that AudioIO::IsActive() returned false.
   //    IsActive() (which calls Pa_GetStreamActive()) will not return
   //    false until all buffers have finished playing, so we can call
   //    AbortStream without losing any samples.  If this is the case
   //    we are in the "callback finished state" (see PortAudio state
   //    machine docs).
   //
   // The moral of the story: We can call AbortStream safely, without
   // losing samples.
   //
   // DMM: This doesn't seem to be true; it seems to be necessary to
   // call StopStream if the callback brought us here, and AbortStream
   // if the user brought us here.
   //
   // DV: Seems that Pa_CloseStream calls Pa_AbortStream internally,
   // at least for PortAudio 19.7.0+
 
   StopAudioThread();
 
   // Turn off HW playthrough if PortMixer is being used
 
  #if defined(USE_PORTMIXER)
   if( mPortMixer ) {
      #if __WXMAC__
      if (Px_SupportsPlaythrough(mPortMixer) && mPreviousHWPlaythrough >= 0.0)
         Px_SetPlaythrough(mPortMixer, mPreviousHWPlaythrough);
         mPreviousHWPlaythrough = -1.0;
      #endif
   }
  #endif
 
   if (mPortStreamV19) {
      // DV: Pa_CloseStream will close Pa_AbortStream internally,
      // but it doesn't hurt to do it ourselves.
      // PA_AbortStream will silently fail if stream is stopped.
      if (!Pa_IsStreamStopped( mPortStreamV19 ))
        Pa_AbortStream( mPortStreamV19 );
 
      Pa_CloseStream( mPortStreamV19 );
 
      mPortStreamV19 = NULL;
   }
 
 
 
   // We previously told AudioThread to stop processing, now let's
   // be sure it has really stopped before resetting mpTransportState
   WaitForAudioThreadStopped();
 
 
   for( auto &ext : Extensions() )
      ext.StopOtherStream();
 
   auto pListener = GetListener();
 
   // If there's no token, we were just monitoring, so we can
   // skip this next part...
   if (mStreamToken > 0) {
      // In either of the above cases, we want to make sure that any
      // capture data that made it into the PortAudio callback makes it
      // to the target RecordableSequence.  To do this, we ask the audio thread
      // to call SequenceBufferExchange one last time (it normally would not do
      // so since Pa_GetStreamActive() would now return false
      ProcessOnceAndWait();
   }
 
   // No longer need effects processing. This must be done after the stream is stopped
   // to prevent the callback from being invoked after the effects are finalized.
   mpTransportState.reset();
 
   //
   // Everything is taken care of.  Now, just free all the resources
   // we allocated in StartStream()
   //
   mPlaybackBuffers.clear();
   mScratchBuffers.clear();
   mScratchPointers.clear();
   mPlaybackMixers.clear();
   mPlaybackSchedule.mTimeQueue.Clear();
 
   if (mStreamToken > 0)
   {
      //
      // Offset all recorded sequences to account for latency
      //
      if (mCaptureSequences.size() > 0) {
         mCaptureBuffers.clear();
         mResample.clear();
 
         //
         // We only apply latency correction when we actually played back
         // sequences during the recording. If we did not play back sequences,
         // there's nothing we could be out of sync with. This also covers the
         // case that we do not apply latency correction when recording the
         // first sequence in a project.
         //
 
         for (auto &sequence : mCaptureSequences) {
            // The calls to Flush
            // may cause exceptions because of exhaustion of disk space.
            // Stop those exceptions here, or else they propagate through too
            // many parts of Audacity that are not effects or editing
            // operations.  GuardedCall ensures that the user sees a warning.
 
            // Also be sure to Flush each sequence, at the top of the
            // guarded call, relying on the guarantee that the sequence will be
            // left in a flushed state, though the append buffer may be lost.
 
            GuardedCall( [&] {
               // use No-fail-guarantee that sequence is flushed,
               // Partial-guarantee that some initial length of the recording
               // is saved.
               // See comments in SequenceBufferExchange().
               sequence->Flush();
            } );
         }
 
 
         if (!mLostCaptureIntervals.empty()) {
            // This scope may combine many insertions of silence
            // into one transaction, lessening the number of checkpoints
            std::optional<TransactionScope> pScope;
            if (auto pOwningProject = mOwningProject.lock())
               pScope.emplace(*pOwningProject, "Dropouts");
            for (auto &interval : mLostCaptureIntervals) {
               auto &start = interval.first;
               auto duration = interval.second;
               for (auto &sequence : mCaptureSequences)
                  GuardedCall([&] {
                     sequence->InsertSilence(start, duration);
                  });
            }
            if (pScope)
               pScope->Commit();
         }
 
         if (pListener)
            pListener->OnCommitRecording();
      }
   }
 
 
 
   if (auto pInputMeter = mInputMeter.lock())
      pInputMeter->Reset(mRate, false);
 
   if (auto pOutputMeter = mOutputMeter.lock())
      pOutputMeter->Reset(mRate, false);
 
   mInputMeter.reset();
   mOutputMeter.reset();
 
   if (pListener && mNumCaptureChannels > 0)
      pListener->OnAudioIOStopRecording();
 
   BasicUI::CallAfter([this]{
      if (mPortStreamV19 && mNumCaptureChannels > 0)
         // Recording was restarted between StopStream and idle time
         // So the actions can keep waiting
         return;
      // In case some other thread was waiting on the mutex too:
      std::this_thread::yield();
      std::lock_guard<std::mutex> guard{ mPostRecordingActionMutex };
      if (mPostRecordingAction) {
         mPostRecordingAction();
         mPostRecordingAction = {};
      }
      DelayActions(false);
   });
 
   //
   // Only set token to 0 after we're totally finished with everything
   //
   bool wasMonitoring = mStreamToken == 0;
   mStreamToken = 0;
 
   {
      auto pOwningProject = mOwningProject.lock();
      if (mNumPlaybackChannels > 0)
         Publish({ pOwningProject.get(), AudioIOEvent::PLAYBACK, false });
      if (mNumCaptureChannels > 0)
         Publish({ pOwningProject.get(),
            wasMonitoring
               ? AudioIOEvent::MONITOR
               : AudioIOEvent::CAPTURE,
            false });
   }
 
   ResetOwningProject();
 
   mNumCaptureChannels = 0;
   mNumPlaybackChannels = 0;
 
   mPlaybackSequences.clear();
   mCaptureSequences.clear();
 
   mPlaybackSchedule.GetPolicy().Finalize( mPlaybackSchedule );
 
   if (pListener) {
      // Tell UI to hide sample rate
      pListener->OnAudioIORate(0);
   }
 
   // Don't cause a busy wait in the audio thread after stopping scrubbing
   mPlaybackSchedule.ResetMode();
}

References AudioIOLatencyDuration, BasicUI::CallAfter(), AudioIOEvent::CAPTURE, PlaybackSchedule::TimeQueue::Clear(), AudioIoCallback::ClearRecordingException(), DelayActions(), AudioIoCallback::Extensions(), PlaybackPolicy::Finalize(), AudioIoCallback::GetListener(), PlaybackSchedule::GetPolicy(), GuardedCall(), AudioIoCallback::mAudioThreadSequenceBufferExchangeLoopRunning, AudioIoCallback::mbMicroFades, AudioIoCallback::mCaptureBuffers, AudioIoCallback::mCaptureSequences, RecordingSchedule::mCrossfadeData, AudioIoCallback::mForceFadeOut, AudioIOBase::mInputMeter, AudioIoCallback::mLostCaptureIntervals, AudioIoCallback::mNumCaptureChannels, AudioIoCallback::mNumPlaybackChannels, AudioIOEvent::MONITOR, AudioIOBase::mOutputMeter, AudioIOBase::mOwningProject, AudioIoCallback::mPlaybackBuffers, AudioIoCallback::mPlaybackMixers, AudioIoCallback::mPlaybackSchedule, AudioIoCallback::mPlaybackSequences, AudioIOBase::mPortStreamV19, mPostRecordingAction, mPostRecordingActionMutex, AudioIoCallback::mpTransportState, AudioIOBase::mRate, AudioIoCallback::mRecordingSchedule, AudioIoCallback::mResample, AudioIoCallback::mScratchBuffers, AudioIoCallback::mScratchPointers, AudioIOBase::mStreamToken, AudioIoCallback::mSuspendAudioThread, PlaybackSchedule::mTimeQueue, AudioIOEvent::PLAYBACK, AudioIoCallback::ProcessOnceAndWait(), Observer::Publisher< AudioIOEvent >::Publish(), Setting< T >::Read(), KeyboardCapture::Release(), PlaybackSchedule::ResetMode(), ResetOwningProject(), AudioIoCallback::StopAudioThread(), and AudioIoCallback::WaitForAudioThreadStopped().

Referenced by DrainRecordBuffers(), and StartStream().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TransformPlayBuffers()

void AudioIO::TransformPlayBuffers ( std::optional< RealtimeEffects::ProcessingScope > & scope )

private

Definition at line 2053 of file AudioIO.cpp.

{
   // Transform written but un-flushed samples in the RingBuffers in-place.
 
   // Avoiding std::vector
   const auto pointers = stackAllocate(float*, mNumPlaybackChannels);
 
   const auto numPlaybackSequences = mPlaybackSequences.size();
   // mPlaybackBuffers correspond many-to-one with mPlaybackSequences
   size_t iBuffer = 0;
   for (const auto vt : mPlaybackSequences) {
      if (!vt)
         continue;
      const auto pGroup = vt->FindChannelGroup();
      if (!pGroup)
         continue;
      // vt is mono, or is the first of its group of channels
      const auto nChannels = std::min<size_t>(
         mNumPlaybackChannels, vt->NChannels());
 
      // Loop over the blocks of unflushed data, at most two
      for (unsigned iBlock : {0, 1}) {
         size_t len = 0;
         size_t iChannel = 0;
         for (; iChannel < nChannels; ++iChannel) {
            auto &ringBuffer = *mPlaybackBuffers[iBuffer + iChannel];
            const auto pair = ringBuffer.GetUnflushed(iBlock);
            // Playback RingBuffers have float format: see AllocateBuffers
            pointers[iChannel] = reinterpret_cast<float*>(pair.first);
            // The lengths of corresponding unflushed blocks should be
            // the same for all channels
            if (len == 0)
               len = pair.second;
            else
               assert(len == pair.second);
         }
 
         // Are there more output device channels than channels of vt?
         // Such as when a mono sequence is processed for stereo play?
         // Then supply some non-null fake input buffers, because the
         // various ProcessBlock overrides of effects may crash without it.
         // But it would be good to find the fixes to make this unnecessary.
         float **scratch = &mScratchPointers[mNumPlaybackChannels + 1];
         while (iChannel < mNumPlaybackChannels)
            memset((pointers[iChannel++] = *scratch++), 0, len * sizeof(float));
 
         if (len && pScope) {
            auto discardable = pScope->Process(*pGroup, &pointers[0],
               mScratchPointers.data(),
               // The single dummy output buffer:
               mScratchPointers[mNumPlaybackChannels],
               mNumPlaybackChannels, len);
            iChannel = 0;
            for (; iChannel < nChannels; ++iChannel) {
               auto &ringBuffer = *mPlaybackBuffers[iBuffer + iChannel];
               auto discarded = ringBuffer.Unput(discardable);
               // assert(discarded == discardable);
            }
         }
      }
      iBuffer += vt->NChannels();
   }
}

References anonymous_namespace{StretchingSequenceIntegrationTest.cpp}::iChannel, AudioIoCallback::mNumPlaybackChannels, AudioIoCallback::mPlaybackBuffers, AudioIoCallback::mPlaybackSequences, AudioIoCallback::mScratchPointers, and stackAllocate.

Referenced by ProcessPlaybackSlices().

Here is the caller graph for this function:

◆ ValidateDeviceNames()

bool AudioIO::ValidateDeviceNames	(	const wxString &	play,
		const wxString &	rec
	)

static

Ensure selected device names are valid.

Definition at line 223 of file AudioIO.cpp.

{
   const PaDeviceInfo *pInfo = Pa_GetDeviceInfo(getPlayDevIndex(play));
   const PaDeviceInfo *rInfo = Pa_GetDeviceInfo(getRecordDevIndex(rec));
 
   // Valid iff both defined and the same api.
   return pInfo != nullptr && rInfo != nullptr && pInfo->hostApi == rInfo->hostApi;
}

References AudioIOBase::getPlayDevIndex(), and AudioIOBase::getRecordDevIndex().

Here is the call graph for this function:

Member Data Documentation

◆ mDelayingActions

bool AudioIO::mDelayingActions { false }

private

Definition at line 663 of file AudioIO.h.

Referenced by DelayActions(), and DelayingActions().

◆ mPostRecordingAction

PostRecordingAction AudioIO::mPostRecordingAction

private

Definition at line 661 of file AudioIO.h.

Referenced by CallAfterRecording(), and StopStream().

◆ mPostRecordingActionMutex

std::mutex AudioIO::mPostRecordingActionMutex

private

Definition at line 660 of file AudioIO.h.

Referenced by CallAfterRecording(), and StopStream().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ PostRecordingAction

Constructor & Destructor Documentation

◆ AudioIO()

◆ ~AudioIO()

Member Function Documentation

◆ AddState()

◆ AllocateBuffers()

◆ AudioThread()

◆ CallAfterRecording()

◆ Deinit()

◆ DelayActions()

◆ DelayingActions()

◆ DrainRecordBuffers()

◆ FillPlayBuffers()

◆ Get()

◆ GetBestRate()

◆ GetCaptureFormat()

◆ GetCommonlyAvailCapture()

◆ GetCommonlyFreePlayback()

◆ GetInputSourceNames()

◆ GetLastPlaybackTime()

◆ GetMixer()

◆ GetNumCaptureChannels()

◆ GetNumPlaybackChannels()

◆ GetOwningProject()

◆ GetStreamTime()

◆ Init()

◆ InputMixerWorks()

◆ IsAvailable()

◆ IsCapturing()

◆ LastPaErrorString()

◆ ProcessPlaybackSlices()

◆ RemoveState()

◆ ReplaceState()

◆ ResetOwningProject()

◆ SeekStream()

◆ SequenceBufferExchange()

◆ SetMeters()

◆ SetMixer()

◆ SetOwningProject()

◆ SetPaused()

◆ StartMonitoring()

◆ StartPortAudioStream()

◆ StartStream()

◆ StartStreamCleanup()

◆ StartThread()

◆ StopStream()

◆ TransformPlayBuffers()

◆ ValidateDeviceNames()

Member Data Documentation

◆ mDelayingActions

◆ mPostRecordingAction

◆ mPostRecordingActionMutex