WaveTrack.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  WaveTrack.h
 
  Dominic Mazzoni
 
**********************************************************************/
 
#ifndef __AUDACITY_WAVETRACK__
#define __AUDACITY_WAVETRACK__
 
#include "ClipInterface.h"
#include "PlaybackDirection.h"
#include "Prefs.h"
#include "SampleCount.h"
#include "SampleFormat.h"
#include "SampleTrack.h"
#include "WideSampleSequence.h"
 
#include <functional>
#include <optional>
#include <vector>
#include <wx/thread.h>
#include <wx/longlong.h>
 
class AudacityProject;
class BlockArray;
 
namespace BasicUI{ class ProgressDialog; }
 
class SampleBlockFactory;
using SampleBlockFactoryPtr = std::shared_ptr<SampleBlockFactory>;
 
class TimeWarper;
 
class ClipInterface;
class Sequence;
class WaveClip;
class WaveClipChannel;
using WaveChannelInterval = WaveClipChannel;
class AudioSegmentSampleView;
 
using WaveClipHolder = std::shared_ptr<WaveClip>;
using WaveClipConstHolder = std::shared_ptr<const WaveClip>;
using WaveClipHolders = std::vector<WaveClipHolder>;
using WaveClipConstHolder = std::shared_ptr<const WaveClip>;
using WaveClipConstHolders = std::vector<WaveClipConstHolder>;
 
using ClipConstHolders = std::vector<std::shared_ptr<const ClipInterface>>;
 
// Temporary arrays of mere pointers
using WaveClipPointers = std::vector < WaveClip* >;
using WaveClipConstPointers = std::vector < const WaveClip* >;
 
using ChannelSampleView = std::vector<AudioSegmentSampleView>;
using ChannelGroupSampleView = std::vector<ChannelSampleView>;
 
using TimeInterval = std::pair<double, double>;
using ProgressReporter = std::function<void(double)>;
 
//
// Tolerance for merging wave tracks (in seconds)
//
#define WAVETRACK_MERGE_POINT_TOLERANCE 0.01
 
class Envelope;
class WaveTrack;
 
struct WaveTrackMessage {
   WaveClipHolder pClip{};
   const enum Type {
      New, 
      Deserialized, 
      Inserted, 
   } type{};
};
 
class WAVE_TRACK_API WaveChannel final
   : public Channel
   , public WideSampleSequence
{
public:
   explicit WaveChannel(WaveTrack &owner);
   ~WaveChannel() override;
 
   inline WaveTrack &GetTrack();
   inline const WaveTrack &GetTrack() const;
 
   AudioGraph::ChannelType GetChannelType() const override;
 
   size_t NChannels() const override;
 
   float GetChannelGain(int channel) const override;
 
   bool DoGet(
      size_t iChannel, size_t nBuffers, const samplePtr buffers[],
      sampleFormat format, sampleCount start, size_t len, bool backwards,
      fillFormat fill = FillFormat::fillZero, bool mayThrow = true,
      // Report how many samples were copied from within clips, rather than
      // filled according to fillFormat; but these were not necessarily one
      // contiguous range.
      sampleCount* pNumWithinClips = nullptr) const override;
 
   double GetStartTime() const override;
   double GetEndTime() const override;
   double GetRate() const override;
   bool HasTrivialEnvelope() const override;
   void GetEnvelopeValues(
      double* buffer, size_t bufferLen, double t0,
      bool backwards) const override;
   sampleFormat WidestEffectiveFormat() const override;
 
   ChannelGroup &DoGetChannelGroup() const override;
 
   std::shared_ptr<WaveClipChannel> GetInterval(size_t iInterval);
   std::shared_ptr<const WaveClipChannel> GetInterval(size_t iInterval) const;
 
   IteratorRange<IntervalIterator<WaveClipChannel>> Intervals();
   IteratorRange<IntervalIterator<const WaveClipChannel>> Intervals() const;
 
   using WideSampleSequence::GetFloats;
 
   bool GetFloats(float *buffer, sampleCount start, size_t len,
      fillFormat fill = FillFormat::fillZero, bool mayThrow = true,
      sampleCount * pNumWithinClips = nullptr) const
   {
      constexpr auto backwards = false;
      return GetFloats(
         0, 1, &buffer, start, len, backwards, fill, mayThrow, pNumWithinClips);
   }
 
   ChannelSampleView GetSampleView(double t0, double t1, bool mayThrow) const;
 
   [[nodiscard]] bool Set(constSamplePtr buffer, sampleFormat format,
      sampleCount start, size_t len,
      sampleFormat effectiveFormat = widestSampleFormat 
   );
 
   [[nodiscard]] bool SetFloats(const float *buffer,
      sampleCount start, size_t len,
      sampleFormat effectiveFormat = widestSampleFormat 
   )
   {
      return Set(reinterpret_cast<constSamplePtr>(buffer), floatSample,
         start, len, effectiveFormat);
   }
 
   bool AppendBuffer(constSamplePtr buffer, sampleFormat format, size_t len, unsigned stride, sampleFormat effectiveFormat);
 
   bool Append(constSamplePtr buffer, sampleFormat format, size_t len);
 
   inline size_t GetBestBlockSize(sampleCount t) const;
   inline size_t GetIdealBlockSize();
   inline size_t GetMaxBlockSize() const;
 
   inline sampleFormat GetSampleFormat() const;
 
private:
   WaveTrack &mOwner;
};
 
class WAVE_TRACK_API WaveTrack final
   : public WritableSampleTrack
   , public Observer::Publisher<WaveTrackMessage>
{
   struct CreateToken {};
public:
   static const char *WaveTrack_tag;
 
   using Interval = WaveClip;
   using IntervalHolder = std::shared_ptr<Interval>;
   using IntervalHolders = std::vector<IntervalHolder>;
   using IntervalConstHolder = std::shared_ptr<const Interval>;
   using IntervalConstHolders = std::vector<IntervalConstHolder>;
 
   struct Region
   {
      Region() : start(0), end(0) {}
      Region(double start_, double end_) : start(start_), end(end_) {}
 
      double start, end;
 
      //used for sorting
      bool operator < (const Region &b) const
      {
         return this->start < b.start;
      }
   };
 
   using Regions = std::vector < Region >;
 
   static wxString GetDefaultAudioTrackNamePreference();
 
   static double ProjectNyquistFrequency(const AudacityProject &project);
 
   //
   // Constructor / Destructor / Duplicator
   //
 
   // Construct and also build all attachments
   static WaveTrack *New( AudacityProject &project );
 
   WaveTrack(CreateToken&&,
      const SampleBlockFactoryPtr &pFactory, sampleFormat format, double rate);
 
   using Holder = std::shared_ptr<WaveTrack>;
 
   static Holder Create(
      const SampleBlockFactoryPtr &pFactory, sampleFormat format, double rate);
 
   const SampleBlockFactoryPtr &GetSampleBlockFactory() const
   { return mpFactory; }
 
   size_t NChannels() const override;
 
   auto GetChannel(size_t iChannel) {
      return this->ChannelGroup::GetChannel<WaveChannel>(iChannel); }
   auto GetChannel(size_t iChannel) const {
      return this->ChannelGroup::GetChannel<const WaveChannel>(iChannel); }
 
   auto Channels() {
      return this->ChannelGroup::Channels<WaveChannel>(); }
   auto Channels() const {
      return this->ChannelGroup::Channels<const WaveChannel>(); }
 
   AudioGraph::ChannelType GetChannelType() const override;
 
   void Init(const WaveTrack &orig);
 private:
   std::ptrdiff_t FindClip(const Interval &clip);
 
   void RemoveClip(std::ptrdiff_t distance);
 
   Track::Holder Clone(bool backup) const override;
 
   friend class WaveTrackFactory;
 
   wxString MakeClipCopyName(const wxString& originalName) const;
   wxString MakeNewClipName() const;
 
public:
 
   virtual ~WaveTrack();
 
   void MoveTo(double o) override;
 
   bool LinkConsistencyFix(bool doFix) override;
 
   double GetStartTime() const override;
   double GetEndTime() const override;
 
   //
   // Identifying the type of track
   //
 
   //
   // WaveTrack parameters
   //
 
   double GetRate() const override;
 
   void SetRate(double newRate);
 
   // Multiplicative factor.  Only converted to dB for display.
   float GetGain() const;
   void SetGain(float newGain);
 
   // -1.0 (left) -> 1.0 (right)
   float GetPan() const;
   void SetPan(float newPan);
 
   float GetChannelGain(int channel) const override;
 
   sampleCount GetVisibleSampleCount() const;
 
   sampleFormat GetSampleFormat() const override;
 
   void ConvertToSampleFormat(sampleFormat format,
      const std::function<void(size_t)> & progressReport = {});
 
   //
   // High-level editing
   //
 
   Track::Holder Cut(double t0, double t1) override;
 
 
   Holder EmptyCopy(size_t nChannels,
      const SampleBlockFactoryPtr &pFactory = {}) const;
 
 
   Holder EmptyCopy(const SampleBlockFactoryPtr &pFactory = {})
   const;
 
   void MakeMono();
 
   Holder MonoToStereo();
 
   /*
    @return a vector of mono tracks, which are in the list that owns `this`
    @pre `GetOwner()`
    */
   std::vector<Holder> SplitChannels();
 
   void SwapChannels();
 
   // If forClipboard is true,
   // and there is no clip at the end time of the selection, then the result
   // will contain a "placeholder" clip whose only purpose is to make
   // GetEndTime() correct.  This clip is not re-copied when pasting.
   Track::Holder Copy(double t0, double t1, bool forClipboard = true)
      const override;
 
   void Clear(double t0, double t1) override;
   void Paste(double t0, const Track &src) override;
   using Track::Paste; // Get the non-virtual overload too
 
   void ClearAndPaste(
      double t0, double t1, const WaveTrack& src, bool preserve = true,
      bool merge = true, const TimeWarper* effectWarper = nullptr,
      bool clearByTrimming = false) /* not override */;
 
   void Silence(double t0, double t1, ProgressReporter reportProgress) override;
   void InsertSilence(double t, double len) override;
 
   void Split(double t0, double t1);
 
   std::pair<IntervalHolder, IntervalHolder> SplitAt(double t);
 
   void ClearAndAddCutLine(double t0, double t1) /* not override */;
 
   Holder SplitCut(double t0, double t1) /* not override */;
 
   // May assume precondition: t0 <= t1
   void SplitDelete(double t0, double t1) /* not override */;
   void Join(
      double t0, double t1,
      const ProgressReporter& reportProgress) /* not override */;
   // May assume precondition: t0 <= t1
   void Disjoin(double t0, double t1) /* not override */;
 
   // May assume precondition: t0 <= t1
   void Trim(double t0, double t1) /* not override */;
 
   /*
    * @param interval Entire track is rendered if nullopt, else only samples
    * within [interval->first, interval->second), in which case clips are split
    * at these boundaries before rendering - if rendering is needed.
    *
    * @pre `!interval.has_value() || interval->first <= interval->second`
    */
   void ApplyPitchAndSpeed(
      std::optional<TimeInterval> interval, ProgressReporter reportProgress);
 
   void SyncLockAdjust(double oldT1, double newT1) override;
 
   bool IsEmpty(double t0, double t1) const;
 
   bool Append(size_t iChannel, constSamplePtr buffer, sampleFormat format,
      size_t len, unsigned int stride = 1,
      sampleFormat effectiveFormat = widestSampleFormat)
   override;
 
   void Flush() override;
 
   void RepairChannels() override;
 
   const ChannelGroup *FindChannelGroup() const override;
   bool GetMute() const override;
   bool GetSolo() const override;
 
 
   bool DoGet(
      size_t iChannel, size_t nBuffers, const samplePtr buffers[],
      sampleFormat format, sampleCount start, size_t len, bool backwards,
      fillFormat fill = FillFormat::fillZero, bool mayThrow = true,
      // Report how many samples were copied from within clips, rather than
      // filled according to fillFormat; but these were not necessarily one
      // contiguous range.
      sampleCount* pNumWithinClips = nullptr) const override;
 
   ChannelGroupSampleView
   GetSampleView(double t0, double t1, bool mayThrow = true) const;
 
   sampleFormat WidestEffectiveFormat() const override;
 
   bool HasTrivialEnvelope() const override;
 
   void GetEnvelopeValues(
      double* buffer, size_t bufferLen, double t0,
      bool backwards) const override;
 
   //
   // Getting information about the track's internal block sizes
   // and alignment for efficiency
   //
 
   // These return a nonnegative number of samples meant to size a memory buffer
   size_t GetBestBlockSize(sampleCount t) const;
   size_t GetMaxBlockSize() const;
   size_t GetIdealBlockSize();
 
   //
   // XMLTagHandler callback methods for loading and saving
   //
 
   bool HandleXMLTag(const std::string_view& tag, const AttributesList& attrs) override;
   void HandleXMLEndTag(const std::string_view& tag) override;
   XMLTagHandler *HandleXMLChild(const std::string_view& tag) override;
   void WriteXML(XMLWriter &xmlFile) const override;
 
   // Returns true if an error occurred while reading from XML
   std::optional<TranslatableString> GetErrorOpening() const override;
 
   //
   // Lock and unlock the track: you must lock the track before
   // doing a copy and paste between projects.
   //
 
   IntervalHolder GetLeftmostClip();
   IntervalConstHolder GetLeftmostClip() const;
 
   IntervalHolder GetRightmostClip();
   IntervalConstHolder GetRightmostClip() const;
 
   ClipConstHolders GetClipInterfaces() const;
 
 
   IntervalHolder
   CreateClip(double offset = .0, const wxString& name = wxEmptyString,
      const Interval *pToCopy = nullptr, bool copyCutlines = true);
 
 
   IntervalHolder CopyClip(const Interval &toCopy, bool copyCutlines);
 
private:
   void CopyWholeClip(const Interval &clip, double t0, bool forClipboard);
   void CopyPartOfClip(const Interval &clip,
      double t0, double t1, bool forClipboard);
   void FinishCopy(double t0, double t1, double endTime, bool forClipboard);
 
   IntervalConstHolders SortedClipArray() const;
   IntervalConstHolder GetClipAtTime(double time) const;
 
   void CreateRight();
 
 
   WaveClipHolder DoCreateClip(
      double offset = .0, const wxString& name = wxEmptyString) const;
 
public:
   IntervalHolder NewestOrNewClip();
 
   IntervalHolder RightmostOrNewClip();
 
   // Get number of clips in this WaveTrack
   int GetNumClips() const;
 
public:
   IntervalHolders SortedIntervalArray();
   IntervalConstHolders SortedIntervalArray() const;
 
 
   bool CanOffsetClips(
      const std::vector<Interval*> &movingClips, 
      double amount, 
      double *allowedAmount = nullptr 
   );
 
   // Before moving a clip into a track (or inserting a clip), use this
   // function to see if the times are valid (i.e. don't overlap with
   // existing clips).
   bool
   CanInsertClip(const Interval& clip, double& slideBy, double tolerance) const;
 
   // Merge two clips, that is append data from clip2 to clip1,
   // then remove clip2 from track.
   // clipidx1 and clipidx2 are indices into the clip list.
   bool MergeClips(int clipidx1, int clipidx2);
 
   // Resample track (i.e. all clips in the track)
   void Resample(int rate, BasicUI::ProgressDialog *progress = NULL);
 
 
   [[nodiscard]] bool SetFloats(const float *const *buffers,
      sampleCount start, size_t len,
      sampleFormat effectiveFormat = widestSampleFormat 
   );
 
   const TypeInfo &GetTypeInfo() const override;
   static const TypeInfo &ClassTypeInfo();
 
   IntervalConstHolder GetNextInterval(
      const Interval& interval, PlaybackDirection searchDirection) const;
 
   IntervalHolder
   GetNextInterval(const Interval& interval, PlaybackDirection searchDirection);
 
   IntervalHolder GetIntervalAtTime(double t);
 
   auto Intervals() { return ChannelGroup::Intervals<Interval>(); }
   auto Intervals() const { return ChannelGroup::Intervals<const Interval>(); }
 
   /*
    @param newClip false if clip has contents from another clip or track
    @pre interval is not already owned by this or any other track
    */
   void InsertInterval(const IntervalHolder& interval,
      bool newClip, bool allowEmpty = false);
 
   void RemoveInterval(const IntervalHolder& interval);
 
   Track::Holder PasteInto(AudacityProject &project, TrackList &list)
      const override;
 
   bool HasClipNamed(const wxString& name) const;
 
   size_t NIntervals() const override;
 
   IntervalHolder GetClip(size_t iInterval);
   IntervalConstHolder GetClip(size_t iInterval) const;
 
   void SetLegacyFormat(sampleFormat format);
 
private:
   bool InsertClip(WaveClipHolders &clips, WaveClipHolder clip,
      bool newClip, bool backup, bool allowEmpty);
 
   void CopyClips(WaveClipHolders &clips,
      SampleBlockFactoryPtr pFactory, const WaveClipHolders &orig, bool backup);
 
   void MergeChannelAttachments(WaveTrack &&other);
 
   void EraseChannelAttachments(size_t index);
 
public:
   int GetClipIndex(const Interval &clip) const;
 
private:
   // May assume precondition: t0 <= t1
   void HandleClear(
      double t0, double t1, bool addCutLines, bool split,
      bool clearByTrimming = false);
 
   /*
    * @brief Copy/Paste operations must preserve beat durations, but time
    * boundaries are expressed in seconds. For pasting to work, source and
    * destination tracks must therefore have equal tempo.
    * @pre Preconditions of `ClearAndPaste`
    * @pre `GetProjectTempo().has_value() && GetProjectTempo() ==
    * src.GetProjectTempo()`
    */
   void ClearAndPasteAtSameTempo(
      double t0, double t1, const WaveTrack& src, bool preserve, bool merge,
      const TimeWarper* effectWarper, bool clearByTrimming);
 
   static void JoinOne(WaveTrack& track, double t0, double t1);
   static void WriteOneXML(const WaveChannel &channel, XMLWriter &xmlFile,
      size_t iChannel, size_t nChannels);
   void ExpandOneCutLine(double cutLinePosition,
      double* cutlineStart, double* cutlineEnd);
   void ApplyPitchAndSpeedOnIntervals(
      const std::vector<IntervalHolder>& intervals,
      const ProgressReporter& reportProgress);
   void
   ReplaceInterval(const IntervalHolder& oldOne, const IntervalHolder& newOne);
 
   std::shared_ptr<WideChannelGroupInterval> DoGetInterval(size_t iInterval)
      override;
   std::shared_ptr<::Channel> DoGetChannel(size_t iChannel) override;
 
   WaveClipHolders &NarrowClips();
   const WaveClipHolders &NarrowClips() const;
 
   //
   // Protected variables
   //
 
   WaveChannel mChannel;
   std::optional<WaveChannel> mRightChannel;
 
   WaveClipHolders mClips;
 
   mutable int  mLegacyRate{ 0 }; 
   sampleFormat mLegacyFormat{ undefinedSample }; 
 
private:
   //Updates rate parameter only in WaveTrackData
   void DoSetRate(double newRate);
   [[nodiscard]] Holder DuplicateWithOtherTempo(double newTempo) const;
 
   bool GetOne(const WaveClipHolders &clips, size_t iChannel,
      samplePtr buffer, sampleFormat format, sampleCount start, size_t len,
      bool backwards, fillFormat fill, bool mayThrow,
      sampleCount* pNumWithinClips) const;
 
   void DoSetPan(float value);
   void DoSetGain(float value);
 
   /*
    @pre `other.NChannels() == 1 || other.NChannels() == NChannels()`
    */
   void PasteWaveTrack(double t0, const WaveTrack &other, bool merge);
   /*
    * @copybrief ClearAndPasteAtSameTempo
    * @pre Preconditions of `PasteWaveTrack`
    * @pre `GetProjectTempo().has_value() && GetProjectTempo() ==
    * other.GetProjectTempo()`
    */
   void
   PasteWaveTrackAtSameTempo(double t0, const WaveTrack& other, bool merge);
 
   bool RateConsistencyCheck() const;
   bool FormatConsistencyCheck() const;
 
   void ApplyPitchAndSpeedOne(
      double t0, double t1, const ProgressReporter& reportProgress);
 
public:
 
   void ZipClips(bool mustAlign = true);
 
private:
   SampleBlockFactoryPtr mpFactory;
 
   wxCriticalSection mFlushCriticalSection;
   wxCriticalSection mAppendCriticalSection;
   double mLegacyProjectFileOffset{ 0 };
 
   friend WaveChannel; // so it can Publish
};
 
ENUMERATE_TRACK_TYPE(WaveTrack);
 
WaveTrack &WaveChannel::GetTrack() {
   auto &result = static_cast<WaveTrack&>(DoGetChannelGroup());
   return result;
}
 
const WaveTrack &WaveChannel::GetTrack() const {
   auto &result = static_cast<const WaveTrack&>(DoGetChannelGroup());
   return result;
}
 
size_t WaveChannel::GetBestBlockSize(sampleCount t) const {
   return GetTrack().GetBestBlockSize(t);
}
 
size_t WaveChannel::GetIdealBlockSize() {
   return GetTrack().GetIdealBlockSize();
}
 
size_t WaveChannel::GetMaxBlockSize() const {
   return GetTrack().GetMaxBlockSize();
}
 
sampleFormat WaveChannel::GetSampleFormat() const {
   return GetTrack().GetSampleFormat();
}
 
class ProjectRate;
 
class WAVE_TRACK_API WaveTrackFactory final
   : public ClientData::Base
{
 public:
   static WaveTrackFactory &Get( AudacityProject &project );
   static const WaveTrackFactory &Get( const AudacityProject &project );
   static WaveTrackFactory &Reset( AudacityProject &project );
   static void Destroy( AudacityProject &project );
 
   WaveTrackFactory(
      const ProjectRate& rate,
      const SampleBlockFactoryPtr &pFactory)
       : mRate{ rate }
       , mpFactory(pFactory)
   {
   }
   WaveTrackFactory( const WaveTrackFactory & ) = delete;
   WaveTrackFactory &operator=( const WaveTrackFactory & ) = delete;
 
   const SampleBlockFactoryPtr &GetSampleBlockFactory() const
   { return mpFactory; }
 
   std::shared_ptr<WaveTrack> Create();
 
   std::shared_ptr<WaveTrack> Create(sampleFormat format, double rate);
 
   WaveTrack::Holder Create(size_t nChannels);
 
   TrackListHolder CreateMany(size_t nChannels);
 
   WaveTrack::Holder Create(size_t nChannels, sampleFormat format, double rate);
 
   TrackListHolder CreateMany(size_t nChannels, sampleFormat format, double rate);
 
   WaveTrack::Holder Create(size_t nChannels, const WaveTrack& proto);
 
 private:
   std::shared_ptr<WaveTrack> DoCreate(
      size_t nChannels, sampleFormat format, double rate);
 
   const ProjectRate &mRate;
   SampleBlockFactoryPtr mpFactory;
};
 
extern WAVE_TRACK_API BoolSetting
     EditClipsCanMove
;
 
extern WAVE_TRACK_API StringSetting AudioTrackNameSetting;
 
WAVE_TRACK_API bool GetEditClipsCanMove();
 
// Generate a registry for serialized data
#include "XMLMethodRegistry.h"
using WaveTrackIORegistry = XMLMethodRegistry<WaveTrack>;
DECLARE_XML_METHOD_REGISTRY( WAVE_TRACK_API, WaveTrackIORegistry );
 
#endif // __AUDACITY_WAVETRACK__