Mixer Class Reference

Functions for doing the mixdown of the tracks. More...

#include <Mix.h>

Collaboration diagram for Mixer:

Classes
struct	Input
struct	Source

Public Types
using	WarpOptions = MixerOptions::Warp
using	MixerSpec = MixerOptions::Downmix
using	ResampleParameters = MixerOptions::ResampleParameters
using	TimesAndSpeed = MixerOptions::TimesAndSpeed
using	Stages = std::vector< MixerOptions::StageSpecification >
using	Inputs = std::vector< Input >

Public Member Functions
	Mixer (Inputs inputs, bool mayThrow, const WarpOptions &warpOptions, double startTime, double stopTime, unsigned numOutChannels, size_t outBufferSize, bool outInterleaved, double outRate, sampleFormat outFormat, bool highQuality=true, MixerSpec *mixerSpec=nullptr, bool applytTrackGains=true)
	Mixer (const Mixer &)=delete
Mixer &	operator= (const Mixer &)=delete
virtual	~Mixer ()
size_t	BufferSize () const
size_t	Process (size_t maxSamples)
size_t	Process ()
void	Restart ()
	Restart processing at beginning of buffer next time Process() is called. More...
void	Reposition (double t, bool bSkipping=false)
	Reposition processing to absolute time next time Process() is called. More...
void	SetTimesAndSpeed (double t0, double t1, double speed, bool bSkipping=false)
	Used in scrubbing and other nonuniform playback policies. More...
void	SetSpeedForKeyboardScrubbing (double speed, double startTime)
double	MixGetCurrentTime ()
	Current time in seconds (unwarped, i.e. always between startTime and stopTime) More...
constSamplePtr	GetBuffer ()
	Retrieve the main buffer or the interleaved buffer. More...
constSamplePtr	GetBuffer (int channel)
	Retrieve one of the non-interleaved buffers. More...
sampleFormat	EffectiveFormat () const
	Deduce the effective width of the output, which may be narrower than the stored format. More...

Private Member Functions
void	Clear ()
std::pair< bool, sampleFormat >	NeedsDither (bool needsDither, double rate) const

Private Attributes
const unsigned	mNumChannels
Inputs	mInputs
const size_t	mBufferSize
const bool	mApplyTrackGains
const bool	mHighQuality
const sampleFormat	mFormat
const bool	mInterleaved
sampleFormat	mEffectiveFormat
bool	mNeedsDither
const std::shared_ptr< TimesAndSpeed >	mTimesAndSpeed
AudioGraph::Buffers	mFloatBuffers
std::vector< std::vector< float > >	mTemp
const std::vector< SampleBuffer >	mBuffer
std::vector< MixerSource >	mSources
std::vector< EffectSettings >	mSettings
std::vector< AudioGraph::Buffers >	mStageBuffers
std::vector< std::unique_ptr< AudioGraph::EffectStage > >	mStages
std::vector< Source >	mDecoratedSources

Detailed Description

Functions for doing the mixdown of the tracks.

Definition at line 26 of file Mix.h.

Member Typedef Documentation

Inputs

using Mixer::Inputs = std::vector<Input>

Definition at line 43 of file Mix.h.

MixerSpec

using Mixer::MixerSpec = MixerOptions::Downmix

Definition at line 29 of file Mix.h.

ResampleParameters

using Mixer::ResampleParameters = MixerOptions::ResampleParameters

Definition at line 30 of file Mix.h.

Stages

using Mixer::Stages = std::vector<MixerOptions::StageSpecification>

Definition at line 32 of file Mix.h.

TimesAndSpeed

using Mixer::TimesAndSpeed = MixerOptions::TimesAndSpeed

Definition at line 31 of file Mix.h.

WarpOptions

using Mixer::WarpOptions = MixerOptions::Warp

Definition at line 28 of file Mix.h.

Constructor & Destructor Documentation

Mixer() [1/2]

Mixer::Mixer	(	Inputs	inputs,
		bool	mayThrow,
		const WarpOptions &	warpOptions,
		double	startTime,
		double	stopTime,
		unsigned	numOutChannels,
		size_t	outBufferSize,
		bool	outInterleaved,
		double	outRate,
		sampleFormat	outFormat,
		bool	highQuality = true,
		MixerSpec *	mixerSpec = nullptr,
		bool	applytTrackGains = true
	)

Precondition

all inputTracks are non-null

any left channels in inputTracks are immediately followed by their partners

Postcondition

BufferSize() <= outBufferSize (equality when no inputs have stages)

Parameters

mixerSpec

Null or else must have a lifetime enclosing this object's

Definition at line 75 of file Mix.cpp.

   : mNumChannels{ numOutChannels }
   , mInputs{ move(inputs) }
   , mBufferSize{ FindBufferSize(mInputs, outBufferSize) }
   , mApplyTrackGains{ applyTrackGains }
   , mHighQuality{ highQuality }
   , mFormat{ outFormat }
   , mInterleaved{ outInterleaved }
 
   , mTimesAndSpeed{ std::make_shared<TimesAndSpeed>( TimesAndSpeed{
      startTime, stopTime, warpOptions.initialSpeed, startTime
   } ) }
 
   // PRL:  Bug2536: see other comments below for the last, padding argument
   // TODO: more-than-two-channels
   // Issue 3565 workaround:  allocate one extra buffer when applying a
   // GVerb effect stage.  It is simply discarded
   // See also issue 3854, when the number of out channels expected by the
   // plug-in is yet larger
   , mFloatBuffers{ 3, mBufferSize, 1, 1 }
 
   // non-interleaved
   , mTemp{ initVector<float>(mNumChannels, mBufferSize) }
   , mBuffer{ initVector<SampleBuffer>(mInterleaved ? 1 : mNumChannels,
      [format = mFormat,
         size = mBufferSize * (mInterleaved ? mNumChannels : 1)
      ](auto &buffer){ buffer.Allocate(size, format); }
   )}
   , mEffectiveFormat{ floatSample }
{
   assert(BufferSize() <= outBufferSize);
   const auto nTracks =  mInputs.size();
 
   // Examine the temporary instances that were made in FindBufferSize
   // This finds a sufficient, but not necessary, condition to do dithering
   bool needsDither = std::any_of(mInputs.begin(), mInputs.end(),
      [](const Input &input){
         return std::any_of(input.stages.begin(), input.stages.end(),
            [](const MixerOptions::StageSpecification &spec){
               return spec.mpFirstInstance &&
                  spec.mpFirstInstance->NeedsDither(); } ); } );
 
   auto pMixerSpec = ( mixerSpec &&
      mixerSpec->GetNumChannels() == mNumChannels &&
      mixerSpec->GetNumTracks() == nTracks
   ) ? mixerSpec : nullptr;
 
   // Reserve vectors first so we can take safe references to pushed elements
   mSources.reserve(nTracks);
   auto nStages = std::accumulate(mInputs.begin(), mInputs.end(), 0,
      [](auto sum, auto &input){ return sum + input.stages.size(); });
   mSettings.reserve(nStages);
   mStageBuffers.reserve(nStages);
 
   for (size_t i = 0; i < nTracks;) {
      const auto &input = mInputs[i];
      const auto leader = input.pTrack.get();
      const auto nInChannels = TrackList::NChannels(*leader);
      if (!leader || i + nInChannels > nTracks) {
         assert(false);
         break;
      }
      auto increment = finally([&]{ i += nInChannels; });
 
      auto &source = mSources.emplace_back( *leader, BufferSize(), outRate,
         warpOptions, highQuality, mayThrow, mTimesAndSpeed,
         (pMixerSpec ? &pMixerSpec->mMap[i] : nullptr));
      AudioGraph::Source *pDownstream = &source;
      for (const auto &stage : input.stages) {
         // Make a mutable copy of stage.settings
         auto &settings = mSettings.emplace_back(stage.settings);
         // TODO: more-than-two-channels
         // Like mFloatBuffers but padding not needed for soxr
         // Allocate one extra buffer to hold dummy zero inputs
         // (Issue 3854)
         auto &stageInput = mStageBuffers.emplace_back(3, mBufferSize, 1);
         const auto &factory = [&stage]{
            // Avoid unnecessary repeated calls to the factory
            return stage.mpFirstInstance
               ? move(stage.mpFirstInstance)
               : stage.factory();
         };
         auto &pNewDownstream =
         mStages.emplace_back(AudioGraph::EffectStage::Create(true,
            *pDownstream, stageInput,
            factory, settings, outRate, std::nullopt, *leader
         ));
         if (pNewDownstream)
            pDownstream = pNewDownstream.get();
         else {
            // Just omit the failed stage from rendering
            // TODO propagate the error?
            mStageBuffers.pop_back();
            mSettings.pop_back();
         }
      }
      mDecoratedSources.emplace_back(Source{ source, *pDownstream });
   }
 
   // Decide once at construction time
   std::tie(mNeedsDither, mEffectiveFormat) = NeedsDither(needsDither, outRate);
}

References format, and size.

Mixer() [2/2]

Mixer::Mixer ( const Mixer &  )

delete

~Mixer()

Mixer::~Mixer ( )

virtual

Definition at line 186 of file Mix.cpp.

{
}

Member Function Documentation

BufferSize()

size_t Mixer::BufferSize ( ) const

inline

Definition at line 70 of file Mix.h.

{ return mBufferSize; }

Referenced by Process().

Here is the caller graph for this function:

Clear()

void Mixer::Clear ( )

private

Definition at line 249 of file Mix.cpp.

{
   for (auto &buffer: mTemp)
      std::fill(buffer.begin(), buffer.end(), 0);
}

References mTemp.

Referenced by Process().

Here is the caller graph for this function:

EffectiveFormat()

sampleFormat Mixer::EffectiveFormat

(

)

const

Deduce the effective width of the output, which may be narrower than the stored format.

Definition at line 386 of file Mix.cpp.

{
   return mEffectiveFormat;
}

References mEffectiveFormat.

Referenced by MixAndRender().

Here is the caller graph for this function:

GetBuffer() [1/2]

constSamplePtr Mixer::GetBuffer

(

)

Retrieve the main buffer or the interleaved buffer.

Definition at line 376 of file Mix.cpp.

{
   return mBuffer[0].ptr();
}

References mBuffer.

Referenced by MixAndRender().

Here is the caller graph for this function:

GetBuffer() [2/2]

constSamplePtr Mixer::GetBuffer

(

int

channel

)

Retrieve one of the non-interleaved buffers.

Definition at line 381 of file Mix.cpp.

{
   return mBuffer[channel].ptr();
}

References mBuffer.

MixGetCurrentTime()

double Mixer::MixGetCurrentTime

(

)

Current time in seconds (unwarped, i.e. always between startTime and stopTime)

This value is not accurate, it's useful for progress bars and indicators, but nothing else.

Definition at line 391 of file Mix.cpp.

{
   return mTimesAndSpeed->mTime;
}

References mTimesAndSpeed.

Referenced by MixAndRender().

Here is the caller graph for this function:

NeedsDither()

std::pair< bool, sampleFormat > Mixer::NeedsDither ( bool  needsDither, double  rate  ) const

private

TODO: more-than-two-channels

Definition at line 191 of file Mix.cpp.

{
   // This will accumulate the widest effective format of any input
   // clip
   auto widestEffectiveFormat = narrowestSampleFormat;
 
   // needsDither may already be given as true.
   // There are many other possible disqualifiers for the avoidance of dither.
   if (std::any_of(mSources.begin(), mSources.end(),
      std::mem_fn(&MixerSource::VariableRates))
   )
      // We will call MixVariableRates(), so we need nontrivial resampling
      needsDither = true;
 
   for (const auto &input : mInputs) {
      auto &pTrack = input.pTrack;
      if (!pTrack)
         continue;
      auto &track = *pTrack;
      if (track.GetRate() != rate)
         // Also leads to MixVariableRates(), needs nontrivial resampling
         needsDither = true;
      if (mApplyTrackGains) {
         for (auto c : {0, 1}) {
            const auto gain = track.GetChannelGain(c);
            if (!(gain == 0.0 || gain == 1.0))
               // Fractional gain may be applied even in MixSameRate
               needsDither = true;
         }
      }
 
      // Examine all tracks.  (This ignores the time bounds for the mixer.
      // If it did not, we might avoid dither in more cases.  But if we fix
      // that, remember that some mixers change their time bounds after
      // construction, as when scrubbing.)
      if (!track.HasTrivialEnvelope())
         // Varying or non-unit gain may be applied even in MixSameRate
         needsDither = true;
      auto effectiveFormat = track.WidestEffectiveFormat();
      if (effectiveFormat > mFormat)
         // Real, not just nominal, precision loss would happen in at
         // least one clip
         needsDither = true;
      widestEffectiveFormat =
         std::max(widestEffectiveFormat, effectiveFormat);
   }
 
   if (needsDither)
      // Results will be dithered to width mFormat
      return { true, mFormat };
   else {
      // Results will not be dithered
      assert(widestEffectiveFormat <= mFormat);
      return { false, widestEffectiveFormat };
   }
}

References mApplyTrackGains, mFormat, mInputs, mSources, narrowestSampleFormat, and MixerSource::VariableRates().

Here is the call graph for this function:

operator=()

Mixer & Mixer::operator= ( const Mixer &  )

delete

Process() [1/2]

size_t Mixer::Process ( )

inline

Postcondition

result: result <= BufferSize()

Definition at line 89 of file Mix.h.

{ return Process(BufferSize()); }

References BufferSize, and Process().

Referenced by Process().

Here is the call graph for this function:

Here is the caller graph for this function:

Process() [2/2]

size_t Mixer::Process

(

size_t

maxSamples

)

Process a maximum of 'maxSamples' samples and put them into the buffer, at GetBuffer().

Precondition

maxSamples <= BufferSize()

Postcondition

result: result <= maxSamples

Returns

number of output samples, or 0, if there are no more samples that must be processed.

Definition at line 272 of file Mix.cpp.

{
   assert(maxToProcess <= BufferSize());
 
   // MB: this is wrong! mT represented warped time, and mTime is too inaccurate to use
   // it here. It's also unnecessary I think.
   //if (mT >= mT1)
   //   return 0;
 
   size_t maxOut = 0;
   const auto channelFlags = stackAllocate(unsigned char, mNumChannels);
   const auto gains = stackAllocate(float, mNumChannels);
   if (!mApplyTrackGains)
      std::fill(gains, gains + mNumChannels, 1.0f);
 
   // Decides which output buffers an input channel accumulates into
   auto findChannelFlags = [&channelFlags, numChannels = mNumChannels]
   (const bool *map, Track::ChannelType channel){
      const auto end = channelFlags + numChannels;
      std::fill(channelFlags, end, 0);
      if (map)
         // ignore left and right when downmixing is customized
         std::copy(map, map + numChannels, channelFlags);
      else switch(channel) {
      case Track::MonoChannel:
      default:
         std::fill(channelFlags, end, 1);
         break;
      case Track::LeftChannel:
         channelFlags[0] = 1;
         break;
      case Track::RightChannel:
         if (numChannels >= 2)
            channelFlags[1] = 1;
         else
            channelFlags[0] = 1;
         break;
      }
      return channelFlags;
   };
 
   auto &[mT0, mT1, _, mTime] = *mTimesAndSpeed;
   auto oldTime = mTime;
   // backwards (as possibly in scrubbing)
   const auto backwards = (mT0 > mT1);
 
   Clear();
   // TODO: more-than-two-channels
   auto maxChannels = std::max(2u, mFloatBuffers.Channels());
 
   for (auto &[ upstream, downstream ] : mDecoratedSources) {
      auto oResult = downstream.Acquire(mFloatBuffers, maxToProcess);
      // One of MixVariableRates or MixSameRate assigns into mTemp[*][*] which
      // are the sources for the CopySamples calls, and they copy into
      // mBuffer[*][*]
      if (!oResult)
         return 0;
      auto result = *oResult;
      maxOut = std::max(maxOut, result);
 
      // Insert effect stages here!  Passing them all channels of the track
 
      const auto limit = std::min<size_t>(upstream.Channels(), maxChannels);
      for (size_t j = 0; j < limit; ++j) {
         const auto pFloat = (const float *)mFloatBuffers.GetReadPosition(j);
         const auto track = upstream.GetChannel(j);
         if (mApplyTrackGains)
            for (size_t c = 0; c < mNumChannels; ++c)
               gains[c] = track->GetChannelGain(c);
         const auto flags =
            findChannelFlags(upstream.MixerSpec(j), track->GetChannel());
         MixBuffers(mNumChannels, flags, gains, *pFloat, mTemp, result);
      }
 
      downstream.Release();
      mFloatBuffers.Advance(result);
      mFloatBuffers.Rotate();
   }
 
   if (backwards)
      mTime = std::clamp(mTime, mT1, oldTime);
   else
      mTime = std::clamp(mTime, oldTime, mT1);
 
   const auto dstStride = (mInterleaved ? mNumChannels : 1);
   auto ditherType = mNeedsDither
      ? (mHighQuality ? gHighQualityDither : gLowQualityDither)
      : DitherType::none;
   for (size_t c = 0; c < mNumChannels; ++c)
      CopySamples((constSamplePtr)mTemp[c].data(), floatSample,
         (mInterleaved
            ? mBuffer[0].ptr() + (c * SAMPLE_SIZE(mFormat))
            : mBuffer[c].ptr()
         ),
         mFormat, maxOut, ditherType,
         1, dstStride);
 
   // MB: this doesn't take warping into account, replaced with code based on mSamplePos
   //mT += (maxOut / mRate);
 
   assert(maxOut <= maxToProcess);
   return maxOut;
}

References _, AudioGraph::Buffers::Advance(), BufferSize(), AudioGraph::Buffers::Channels(), Clear(), staffpad::vo::copy(), CopySamples(), PackedArray::end(), floatSample, AudioGraph::Buffers::GetReadPosition(), gHighQualityDither, gLowQualityDither, Track::LeftChannel, mApplyTrackGains, mBuffer, mDecoratedSources, mFloatBuffers, mFormat, mHighQuality, mInterleaved, MixBuffers(), mNeedsDither, mNumChannels, Track::MonoChannel, mTemp, mTimesAndSpeed, none, Track::RightChannel, AudioGraph::Buffers::Rotate(), SAMPLE_SIZE, and stackAllocate.

Referenced by MixAndRender().

Here is the call graph for this function:

Here is the caller graph for this function:

Reposition()

void Mixer::Reposition	(	double	t,
		bool	bSkipping = false
	)

Reposition processing to absolute time next time Process() is called.

Definition at line 418 of file Mix.cpp.

{
   auto &[mT0, mT1, _, mTime] = *mTimesAndSpeed;
   mTime = t;
   const bool backwards = (mT1 < mT0);
   if (backwards)
      mTime = std::clamp(mTime, mT1, mT0);
   else
      mTime = std::clamp(mTime, mT0, mT1);
 
   for (auto &source : mSources)
      source.Reposition(mTime, bSkipping);
}

References _, mSources, and mTimesAndSpeed.

Referenced by SetSpeedForKeyboardScrubbing(), and SetTimesAndSpeed().

Here is the caller graph for this function:

Restart()

void Mixer::Restart

(

)

Restart processing at beginning of buffer next time Process() is called.

SetSpeedForKeyboardScrubbing()

void Mixer::SetSpeedForKeyboardScrubbing	(	double	speed,
		double	startTime
	)

Definition at line 442 of file Mix.cpp.

{
   wxASSERT(std::isfinite(speed));
   auto &[mT0, mT1, mSpeed, _] = *mTimesAndSpeed;
 
   // Check if the direction has changed
   if ((speed > 0.0 && mT1 < mT0) || (speed < 0.0 && mT1 > mT0)) {
      // It's safe to use 0 and std::numeric_limits<double>::max(),
      // because Mixer::MixVariableRates() doesn't sample past the start
      // or end of the audio in a track.
      if (speed > 0.0 && mT1 < mT0) {
         mT0 = 0;
         mT1 = std::numeric_limits<double>::max();
      }
      else {
         mT0 = std::numeric_limits<double>::max();
         mT1 = 0;
      }
 
      Reposition(startTime, true);
   }
 
   mSpeed = fabs(speed);
}

References _, mTimesAndSpeed, and Reposition().

Here is the call graph for this function:

SetTimesAndSpeed()

void Mixer::SetTimesAndSpeed	(	double	t0,
		double	t1,
		double	speed,
		bool	bSkipping = false
	)

Used in scrubbing and other nonuniform playback policies.

Definition at line 432 of file Mix.cpp.

{
   wxASSERT(std::isfinite(speed));
   auto &[mT0, mT1, mSpeed, _] = *mTimesAndSpeed;
   mT0 = t0;
   mT1 = t1;
   mSpeed = fabs(speed);
   Reposition(t0, bSkipping);
}

References _, mTimesAndSpeed, and Reposition().

Here is the call graph for this function:

Member Data Documentation

mApplyTrackGains

const bool Mixer::mApplyTrackGains

private

Definition at line 134 of file Mix.h.

Referenced by NeedsDither(), and Process().

mBuffer

const std::vector<SampleBuffer> Mixer::mBuffer

private

Definition at line 156 of file Mix.h.

Referenced by GetBuffer(), and Process().

mBufferSize

const size_t Mixer::mBufferSize

private

Definition at line 126 of file Mix.h.

mDecoratedSources

std::vector<Source> Mixer::mDecoratedSources

private

Definition at line 164 of file Mix.h.

Referenced by Process().

mEffectiveFormat

sampleFormat Mixer::mEffectiveFormat

private

Definition at line 140 of file Mix.h.

Referenced by EffectiveFormat().

mFloatBuffers

AudioGraph::Buffers Mixer::mFloatBuffers

private

Definition at line 148 of file Mix.h.

Referenced by Process().

mFormat

const sampleFormat Mixer::mFormat

private

Definition at line 136 of file Mix.h.

Referenced by NeedsDither(), and Process().

mHighQuality

const bool Mixer::mHighQuality

private

Definition at line 135 of file Mix.h.

Referenced by Process().

mInputs

Inputs Mixer::mInputs

private

Definition at line 123 of file Mix.h.

Referenced by NeedsDither().

mInterleaved

const bool Mixer::mInterleaved

private

Definition at line 137 of file Mix.h.

Referenced by Process().

mNeedsDither

bool Mixer::mNeedsDither

private

Definition at line 141 of file Mix.h.

Referenced by Process().

mNumChannels

const unsigned Mixer::mNumChannels

private

Definition at line 122 of file Mix.h.

Referenced by Process().

mSettings

std::vector<EffectSettings> Mixer::mSettings

private

Definition at line 159 of file Mix.h.

mSources

std::vector<MixerSource> Mixer::mSources

private

Definition at line 158 of file Mix.h.

Referenced by NeedsDither(), and Reposition().

mStageBuffers

std::vector<AudioGraph::Buffers> Mixer::mStageBuffers

private

Definition at line 160 of file Mix.h.

mStages

std::vector<std::unique_ptr<AudioGraph::EffectStage> > Mixer::mStages

private

Definition at line 161 of file Mix.h.

mTemp

std::vector<std::vector<float> > Mixer::mTemp

private

Definition at line 153 of file Mix.h.

Referenced by Clear(), and Process().

mTimesAndSpeed

const std::shared_ptr<TimesAndSpeed> Mixer::mTimesAndSpeed

private

Definition at line 143 of file Mix.h.

Referenced by MixGetCurrentTime(), Process(), Reposition(), SetSpeedForKeyboardScrubbing(), and SetTimesAndSpeed().

---

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

• Mix.h
• Mix.cpp