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.GetTrackTime() has reached the end of playback. More...
 
virtual double OffsetTrackTime (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::TrackBufferExchange. 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 74 of file PlaybackSchedule.h.

Member Typedef Documentation

◆ Duration

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

Definition at line 76 of file PlaybackSchedule.h.

◆ Mixers

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

Definition at line 142 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 NewDefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 118 of file PlaybackSchedule.cpp.

120{
121 auto realDuration = nSamples / mRate;
122 if (schedule.ReversedTime())
123 realDuration *= -1.0;
124
125 if (schedule.mEnvelope)
126 trackTime =
127 schedule.SolveWarpedLength(trackTime, realDuration);
128 else
129 trackTime += realDuration;
130
131 if ( trackTime >= schedule.mT1 )
132 return { schedule.mT1, std::numeric_limits<double>::infinity() };
133 else
134 return { trackTime, trackTime };
135}
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 NewDefaultPlaybackPolicy::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 60 of file PlaybackSchedule.cpp.

61{
62 return true;
63}

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.GetTrackTime() has reached the end of playback.

Parameters
outputFrameshow many playback frames were taken from RingBuffers

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

Definition at line 65 of file PlaybackSchedule.cpp.

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

References PlaybackSchedule::GetTrackTime(), 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 30 of file PlaybackSchedule.cpp.

30{}

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 NewDefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 92 of file PlaybackSchedule.cpp.

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

Referenced by AudioIO::ProcessPlaybackSlices().

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

◆ Initialize()

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

Called before starting an audio stream.

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

Definition at line 25 of file PlaybackSchedule.cpp.

26{
27 mRate = rate;
28}

References mRate.

Referenced by NewDefaultPlaybackPolicy::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 NewDefaultPlaybackPolicy.

Definition at line 143 of file PlaybackSchedule.cpp.

144{
145 return false;
146}

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 NewDefaultPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 32 of file PlaybackSchedule.cpp.

33{
34 return Mixer::WarpOptions{ schedule.mEnvelope };
35}
Immutable structure is an argument to Mixer's constructor.
Definition: MixerOptions.h:54

References PlaybackSchedule::mEnvelope.

Referenced by NewDefaultPlaybackPolicy::MixerWarpOptions().

Here is the caller graph for this function:

◆ OffsetTrackTime()

double PlaybackPolicy::OffsetTrackTime ( 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::GetTrackTime()
Returns
the new value that will be set as the schedule's track time

Reimplemented in anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy.

Definition at line 77 of file PlaybackSchedule.cpp.

79{
80 const auto time = schedule.GetTrackTime() + offset;
81 schedule.RealTimeInit( time );
82 return time;
83}
void RealTimeInit(double trackTime)

References PlaybackSchedule::GetTrackTime(), 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 NewDefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 137 of file PlaybackSchedule.cpp.

139{
140 return true;
141}

Referenced by NewDefaultPlaybackPolicy::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::TrackBufferExchange.

by the main thread

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 85 of file PlaybackSchedule.cpp.

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

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 NewDefaultPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 38 of file PlaybackSchedule.cpp.

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

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: