Audacity 3.2.0
Classes | Public Types | Public Member Functions | Protected Attributes | List of all members
PlaybackPolicy Class Referenceabstract

Directs which parts of tracks to fetch for playback. More...

#include <PlaybackSchedule.h>

Inheritance diagram for PlaybackPolicy:
[legend]

Classes

struct  BufferTimes
 Times are in seconds. More...
 

Public Types

using Duration = std::chrono::duration< double >
 
using Mixers = std::vector< std::unique_ptr< Mixer > >
 

Public Member Functions

virtual ~PlaybackPolicy ()=0
 
virtual void Initialize (PlaybackSchedule &schedule, double rate)
 Called before starting an audio stream. More...
 
virtual void Finalize (PlaybackSchedule &schedule)
 Called after stopping of an audio stream or an unsuccessful start. More...
 
virtual Mixer::WarpOptions MixerWarpOptions (PlaybackSchedule &schedule)
 Options to use when constructing mixers for each playback track. More...
 
virtual BufferTimes SuggestedBufferTimes (PlaybackSchedule &schedule)
 Provide hints for construction of playback RingBuffer objects. More...
 
virtual bool AllowSeek (PlaybackSchedule &schedule)
 Whether repositioning commands are allowed during playback. More...
 
virtual bool Done (PlaybackSchedule &schedule, unsigned long outputFrames)
 Returns true if schedule.GetSequenceTime() has reached the end of playback. More...
 
virtual double OffsetSequenceTime (PlaybackSchedule &schedule, double offset)
 Called when the play head needs to jump a certain distance. More...
 
virtual std::chrono::milliseconds SleepInterval (PlaybackSchedule &schedule)
 How long to wait between calls to AudioIO::SequenceBufferExchange. More...
 
virtual PlaybackSlice GetPlaybackSlice (PlaybackSchedule &schedule, size_t available)
 Choose length of one fetch of samples from tracks in a call to AudioIO::FillPlayBuffers. More...
 
virtual std::pair< double, double > AdvancedTrackTime (PlaybackSchedule &schedule, double trackTime, size_t nSamples)
 Compute a new point in a track's timeline from an old point and a real duration. More...
 
virtual bool RepositionPlayback (PlaybackSchedule &schedule, const Mixers &playbackMixers, size_t frames, size_t available)
 AudioIO::FillPlayBuffers calls this to update its cursors into tracks for changes of position or speed. More...
 
virtual bool Looping (const PlaybackSchedule &schedule) const
 

Protected Attributes

double mRate = 0
 

Detailed Description

Directs which parts of tracks to fetch for playback.

A non-default policy object may be created each time playback begins, and if so it is destroyed when playback stops, not reused in the next playback.

Methods of the object are passed a PlaybackSchedule as context.

Definition at line 71 of file PlaybackSchedule.h.

Member Typedef Documentation

◆ Duration

using PlaybackPolicy::Duration = std::chrono::duration<double>

Definition at line 73 of file PlaybackSchedule.h.

◆ Mixers

using PlaybackPolicy::Mixers = std::vector<std::unique_ptr<Mixer> >

Definition at line 139 of file PlaybackSchedule.h.

Constructor & Destructor Documentation

◆ ~PlaybackPolicy()

PlaybackPolicy::~PlaybackPolicy ( )
pure virtualdefault

by the main thread

Member Function Documentation

◆ AdvancedTrackTime()

std::pair< double, double > PlaybackPolicy::AdvancedTrackTime ( PlaybackSchedule schedule,
double  trackTime,
size_t  nSamples 
)
virtual

Compute a new point in a track's timeline from an old point and a real duration.

Needed because playback might be at non-unit speed.

Called one or more times between GetPlaybackSlice and RepositionPlayback, until the sum of the nSamples values equals the most recent playback slice (including any trailing silence).

Returns
a pair, which indicates a discontinuous jump when its members are not equal, or specially the end of playback when the second member is infinite

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 117 of file PlaybackSchedule.cpp.

119{
120 auto realDuration = nSamples / mRate;
121 if (schedule.ReversedTime())
122 realDuration *= -1.0;
123
124 if (schedule.mEnvelope)
125 trackTime =
126 schedule.SolveWarpedLength(trackTime, realDuration);
127 else
128 trackTime += realDuration;
129
130 if ( trackTime >= schedule.mT1 )
131 return { schedule.mT1, std::numeric_limits<double>::infinity() };
132 else
133 return { trackTime, trackTime };
134}
double mT1
Playback ends at offset of mT1, which is measured in seconds. Note that mT1 may be less than mT0 duri...
double SolveWarpedLength(double t0, double length) const
Compute how much unwarped time must have elapsed if length seconds of warped time has elapsed,...
bool ReversedTime() const
True if the end time is before the start time.
const BoundedEnvelope * mEnvelope

References PlaybackSchedule::mEnvelope, mRate, PlaybackSchedule::mT1, PlaybackSchedule::ReversedTime(), and PlaybackSchedule::SolveWarpedLength().

Referenced by DefaultPlaybackPolicy::AdvancedTrackTime().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ AllowSeek()

bool PlaybackPolicy::AllowSeek ( PlaybackSchedule schedule)
virtual

Whether repositioning commands are allowed during playback.

by the main thread

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 58 of file PlaybackSchedule.cpp.

59{
60 return true;
61}

Referenced by AudioIoCallback::FillOutputBuffers().

Here is the caller graph for this function:

◆ Done()

bool PlaybackPolicy::Done ( PlaybackSchedule schedule,
unsigned long  outputFrames 
)
virtual

Returns true if schedule.GetSequenceTime() has reached the end of playback.

Parameters
outputFrameshow many playback frames were taken from RingBuffers

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 63 of file PlaybackSchedule.cpp.

65{
66 // Called from portAudio thread, use GetSequenceTime()
67 auto diff = schedule.GetSequenceTime() - schedule.mT1;
68 if (schedule.ReversedTime())
69 diff *= -1;
70 return sampleCount(floor(diff * mRate + 0.5)) >= 0 &&
71 // Require also that output frames are all consumed from ring buffer
72 outputFrames == 0;
73}
Positions or offsets within audio files need a wide type.
Definition: SampleCount.h:19
double GetSequenceTime() const
Get current track time value, unadjusted.

References PlaybackSchedule::GetSequenceTime(), mRate, PlaybackSchedule::mT1, and PlaybackSchedule::ReversedTime().

Referenced by AudioIoCallback::CallbackCheckCompletion(), and AudioIoCallback::DrainInputBuffers().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ Finalize()

void PlaybackPolicy::Finalize ( PlaybackSchedule schedule)
virtual

Called after stopping of an audio stream or an unsuccessful start.

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 28 of file PlaybackSchedule.cpp.

28{}

Referenced by AudioIO::StartStreamCleanup(), and AudioIO::StopStream().

Here is the caller graph for this function:

◆ GetPlaybackSlice()

PlaybackSlice PlaybackPolicy::GetPlaybackSlice ( PlaybackSchedule schedule,
size_t  available 
)
virtual

Choose length of one fetch of samples from tracks in a call to AudioIO::FillPlayBuffers.

Parameters
availableupper bound for the length of the fetch

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 91 of file PlaybackSchedule.cpp.

92{
93 // How many samples to produce for each channel.
94 const auto realTimeRemaining = schedule.RealTimeRemaining();
95 auto frames = available;
96 auto toProduce = frames;
97 double deltat = frames / mRate;
98
99 if (deltat > realTimeRemaining)
100 {
101 // Produce some extra silence so that the time queue consumer can
102 // satisfy its end condition
103 const double extraRealTime = (TimeQueueGrainSize + 1) / mRate;
104 auto extra = std::min( extraRealTime, deltat - realTimeRemaining );
105 auto realTime = realTimeRemaining + extra;
106 frames = realTime * mRate + 0.5;
107 toProduce = realTimeRemaining * mRate + 0.5;
108 schedule.RealTimeAdvance( realTime );
109 }
110 else
111 schedule.RealTimeAdvance( deltat );
112
113 return { available, frames, toProduce };
114}
int min(int a, int b)
constexpr size_t TimeQueueGrainSize
double RealTimeRemaining() const
void RealTimeAdvance(double increment)

References min(), mRate, PlaybackSchedule::RealTimeAdvance(), PlaybackSchedule::RealTimeRemaining(), and TimeQueueGrainSize.

Here is the call graph for this function:

◆ Initialize()

void PlaybackPolicy::Initialize ( PlaybackSchedule schedule,
double  rate 
)
virtual

Called before starting an audio stream.

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 23 of file PlaybackSchedule.cpp.

24{
25 mRate = rate;
26}

References mRate.

Referenced by DefaultPlaybackPolicy::Initialize(), anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy::Initialize(), ScrubbingPlaybackPolicy::Initialize(), and AudioIO::StartStream().

Here is the caller graph for this function:

◆ Looping()

bool PlaybackPolicy::Looping ( const PlaybackSchedule schedule) const
virtual

be removed

Reimplemented in DefaultPlaybackPolicy.

Definition at line 142 of file PlaybackSchedule.cpp.

143{
144 return false;
145}

Referenced by anonymous_namespace{MIDIPlay.h}::MIDIPlay::FillOtherBuffers(), and anonymous_namespace{MIDIPlay.h}::Iterator::OutputEvent().

Here is the caller graph for this function:

◆ MixerWarpOptions()

Mixer::WarpOptions PlaybackPolicy::MixerWarpOptions ( PlaybackSchedule schedule)
virtual

Options to use when constructing mixers for each playback track.

Reimplemented in DefaultPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 30 of file PlaybackSchedule.cpp.

31{
32 return Mixer::WarpOptions{ schedule.mEnvelope };
33}
Immutable structure is an argument to Mixer's constructor.
Definition: MixerOptions.h:56

References PlaybackSchedule::mEnvelope.

Referenced by DefaultPlaybackPolicy::MixerWarpOptions().

Here is the caller graph for this function:

◆ OffsetSequenceTime()

double PlaybackPolicy::OffsetSequenceTime ( PlaybackSchedule schedule,
double  offset 
)
virtual

Called when the play head needs to jump a certain distance.

Parameters
offsetsigned amount requested to be added to schedule::GetSequenceTime()
Returns
the new value that will be set as the schedule's track time

Reimplemented in DefaultPlaybackPolicy, and anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy.

Definition at line 75 of file PlaybackSchedule.cpp.

77{
78 auto time = schedule.GetSequenceTime() + offset;
79 time = std::clamp(time, schedule.mT0, schedule.mT1);
80 schedule.RealTimeInit( time );
81 return time;
82}
double mT0
Playback starts at offset of mT0, which is measured in seconds.
void RealTimeInit(double trackTime)

References PlaybackSchedule::GetSequenceTime(), PlaybackSchedule::mT0, PlaybackSchedule::mT1, and PlaybackSchedule::RealTimeInit().

Referenced by AudioIoCallback::CallbackDoSeek(), and AudioIO::StartStream().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ RepositionPlayback()

bool PlaybackPolicy::RepositionPlayback ( PlaybackSchedule schedule,
const Mixers playbackMixers,
size_t  frames,
size_t  available 
)
virtual

AudioIO::FillPlayBuffers calls this to update its cursors into tracks for changes of position or speed.

Returns
if true, AudioIO::FillPlayBuffers stops producing samples even if space remains
Parameters
frameshow many samples were just now buffered for play
availablehow many more samples may be buffered

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 136 of file PlaybackSchedule.cpp.

138{
139 return true;
140}

Referenced by DefaultPlaybackPolicy::RepositionPlayback().

Here is the caller graph for this function:

◆ SleepInterval()

std::chrono::milliseconds PlaybackPolicy::SleepInterval ( PlaybackSchedule schedule)
virtual

How long to wait between calls to AudioIO::SequenceBufferExchange.

by the main thread

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 84 of file PlaybackSchedule.cpp.

85{
86 using namespace std::chrono;
87 return 10ms;
88}

Referenced by AudioIO::AudioThread().

Here is the caller graph for this function:

◆ SuggestedBufferTimes()

PlaybackPolicy::BufferTimes PlaybackPolicy::SuggestedBufferTimes ( PlaybackSchedule schedule)
virtual

Provide hints for construction of playback RingBuffer objects.

Reimplemented in DefaultPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 36 of file PlaybackSchedule.cpp.

37{
38 using namespace std::chrono;
39#if 1
40 // Shorter times than in the default policy so that responses, to changes of
41 // loop region or speed slider or other such controls, don't lag too much
42 return { 0.05s, 0.05s, 0.25s };
43#else
44/*
45The old values, going very far back.
46
47There are old comments in the code about larger batches of work filling the
48queue with samples, to reduce CPU usage. Maybe this doesn't matter with most
49modern machines, or maybe there will prove to be a need to choose the numbers
50more smartly than these hardcoded values. Maybe we will need to figure out
51adaptiveness of the buffer size by detecting how long the work takes. Maybe
52we can afford even smaller times.
53*/
54 return { 4.0s, 4.0s, 10.0s };
55#endif
56}

Referenced by AudioIO::AllocateBuffers().

Here is the caller graph for this function:

Member Data Documentation

◆ mRate

double PlaybackPolicy::mRate = 0
protected

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