WaveClip.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  WaveClip.h
 
  ?? Dominic Mazzoni
  ?? Markus Meyer
 
*******************************************************************/
#ifndef __AUDACITY_WAVECLIP__
#define __AUDACITY_WAVECLIP__
 
#include "Channel.h"
#include "ClientData.h"
#include "CRTPBase.h"
#include "SampleFormat.h"
#include "ClipInterface.h"
#include "XMLTagHandler.h"
#include "SampleCount.h"
#include "AudioSegmentSampleView.h"
 
#include <wx/longlong.h>
 
#include <cassert>
#include <functional>
#include <optional>
#include <vector>
 
class BlockArray;
class Envelope;
class sampleCount;
class SampleBlock;
class SampleBlockFactory;
using SampleBlockFactoryPtr = std::shared_ptr<SampleBlockFactory>;
class Sequence;
class wxFileNameWrapper;
namespace BasicUI { class ProgressDialog; }
 
class WaveClip;
 
// Array of pointers that assume ownership
using WaveClipHolder = std::shared_ptr<WaveClip>;
using WaveClipConstHolder = std::shared_ptr<const WaveClip>;
using WaveClipHolders = std::vector <WaveClipHolder>;
using WaveClipConstHolders = std::vector<WaveClipConstHolder>;
using ProgressReporter = std::function<void(double)>;
 
struct WAVE_TRACK_API WaveClipListener;
CRTP_BASE(WaveClipListenerBase, struct,
   ClientData::Cloneable<WaveClipListener>);
struct WaveClipListener : WaveClipListenerBase {
   virtual ~WaveClipListener() = 0;
   virtual void MarkChanged() noexcept = 0;
   virtual void Invalidate() = 0;
 
   // Default implementation does nothing
   virtual void WriteXMLAttributes(XMLWriter &writer) const;
 
   // Default implementation just returns false
   virtual bool HandleXMLAttribute(
      const std::string_view &attr, const XMLAttributeValueView &valueView);
 
 
   virtual void MakeStereo(WaveClipListener &&other, bool aligned);
 
   virtual void SwapChannels();
 
 
   virtual void Erase(size_t index);
};
 
class WAVE_TRACK_API WaveClipChannel
   : public ChannelInterval
   , public ClipTimes
{
public:
   WaveClipChannel(WaveClip &clip, size_t iChannel)
      : mClip{ clip }
      , miChannel{ iChannel }
   {}
   ~WaveClipChannel() override;
 
   WaveClip &GetClip() { return mClip; }
   const WaveClip &GetClip() const { return mClip; }
 
   size_t GetChannelIndex() const { return miChannel; }
 
   Envelope &GetEnvelope();
   const Envelope &GetEnvelope() const;
 
   bool Intersects(double t0, double t1) const;
   double Start() const;
   double End() const;
 
   AudioSegmentSampleView
   GetSampleView(double t0, double t1, bool mayThrow) const;
 
   bool WithinPlayRegion(double t) const;
   double SamplesToTime(sampleCount s) const noexcept;
   bool HasPitchOrSpeed() const;
 
   double GetTrimLeft() const;
   double GetTrimRight() const;
 
   bool GetSamples(samplePtr buffer, sampleFormat format,
      sampleCount start, size_t len, bool mayThrow = true) const;
 
   AudioSegmentSampleView GetSampleView(
      sampleCount start, size_t length, bool mayThrow) const;
 
   const Sequence &GetSequence() const;
 
   constSamplePtr GetAppendBuffer() const;
   size_t GetAppendBufferLen() const;
 
   const BlockArray *GetSequenceBlockArray() const;
 
   std::pair<float, float> GetMinMax(double t0, double t1, bool mayThrow) const;
 
   float GetRMS(double t0, double t1, bool mayThrow) const;
 
   sampleCount GetPlayStartSample() const;
 
   sampleCount GetPlayEndSample() const;
 
   void SetSamples(constSamplePtr buffer, sampleFormat format,
      sampleCount start, size_t len,
      sampleFormat effectiveFormat 
   );
 
   void WriteXML(XMLWriter &xmlFile) const;
 
   // implement ClipTimes
   sampleCount GetVisibleSampleCount() const override;
   int GetRate() const override;
   double GetPlayStartTime() const override;
   double GetPlayEndTime() const override;
   double GetPlayDuration() const;
   sampleCount TimeToSamples(double time) const override;
   double GetStretchRatio() const override;
 
   friend inline bool operator ==(
      const WaveClipChannel &a, const WaveClipChannel &b)
   { return &a.mClip == &b.mClip && a.miChannel == b.miChannel; }
   friend inline bool operator !=(
      const WaveClipChannel &a, const WaveClipChannel &b)
   { return !(a == b); }
 
private:
   WaveClip &mClip;
   const size_t miChannel;
};
 
struct CentShiftChange
{
   explicit CentShiftChange(int newValue)
       : newValue(newValue)
   {
   }
   const int newValue;
};
 
struct PitchAndSpeedPresetChange
{
   explicit PitchAndSpeedPresetChange(PitchAndSpeedPreset newValue)
       : newValue(newValue)
   {
   }
   const PitchAndSpeedPreset newValue;
};
 
struct StretchRatioChange
{
   explicit StretchRatioChange(double newValue)
       : newValue(newValue)
   {
   }
   const double newValue;
};
 
struct WaveClipDtorCalled
{
};
 
class WAVE_TRACK_API WaveClip final :
    public ClipInterface,
    public WideChannelGroupInterval,
    public XMLTagHandler,
    public ClientData::Site<
      WaveClip, WaveClipListener, ClientData::DeepCopying>,
    public Observer::Publisher<CentShiftChange>,
    public Observer::Publisher<PitchAndSpeedPresetChange>,
    public Observer::Publisher<StretchRatioChange>,
    public Observer::Publisher<WaveClipDtorCalled>
{
private:
   struct CreateToken{ bool emptyCopy = false; };
 
   // It is an error to copy a WaveClip without specifying the
   // sample block factory.
 
   WaveClip(const WaveClip&) = delete;
   WaveClip& operator= (const WaveClip&) = delete;
 
public:
   static const char *WaveClip_tag;
 
   using Attachments = Site<WaveClip, WaveClipListener, ClientData::DeepCopying>;
 
 
   WaveClip(size_t width,
      const SampleBlockFactoryPtr &factory, sampleFormat format,
      int rate);
 
 
   WaveClip(const WaveClip& orig,
            const SampleBlockFactoryPtr &factory,
            bool copyCutlines)
      : WaveClip{ orig, factory, copyCutlines, {} }
   {}
 
 
   WaveClip(const WaveClip& orig,
            const SampleBlockFactoryPtr &factory,
            bool copyCutlines,
            double t0, double t1);
 
   virtual ~WaveClip();
 
   // Satisfying WideChannelGroupInterval
   double Start() const override;
   double End() const override;
   std::shared_ptr<ChannelInterval> DoGetChannel(size_t iChannel) override;
 
   using Channel = WaveClipChannel;
 
   auto Channels() { return
      WideChannelGroupInterval::Channels<Channel>(); }
 
   auto Channels() const { return
      WideChannelGroupInterval::Channels<const Channel>(); }
 
 
   bool CheckInvariants() const;
 
   bool StrongInvariant() const;
 
 
   void AssertOrRepairStrongInvariant();
 
   struct StrongInvariantScope {
      explicit StrongInvariantScope(WaveClip &clip);
      ~StrongInvariantScope();
   private:
      WaveClip &mClip;
   };
 
   size_t NChannels() const override;
 
   void ConvertToSampleFormat(sampleFormat format,
      const std::function<void(size_t)> & progressReport = {});
 
   int GetRate() const override
   {
      return mRate;
   }
 
   // Set rate without resampling. This will change the length of the clip
   void SetRate(int rate);
   void SetRawAudioTempo(double tempo);
 
   PitchAndSpeedPreset GetPitchAndSpeedPreset() const;
 
   void StretchLeftTo(double to);
   void StretchRightTo(double to);
   void StretchBy(double ratio);
 
   double GetStretchRatio() const override;
 
   bool HasEqualPitchAndSpeed(const WaveClip& other) const;
   bool HasPitchOrSpeed() const;
 
   /*
    * @post `true` if `TimeAndPitchInterface::MinCent <= cents && cents <=
    * TimeAndPitchInterface::MaxCent`
    */
   bool SetCentShift(int cents);
   int GetCentShift() const override;
   [[nodiscard]] Observer::Subscription
   SubscribeToCentShiftChange(std::function<void(int)> cb) const override;
 
   void SetPitchAndSpeedPreset(PitchAndSpeedPreset preset);
   [[nodiscard]] virtual Observer::Subscription
   SubscribeToPitchAndSpeedPresetChange(
      std::function<void(PitchAndSpeedPreset)> cb) const override;
 
   // Resample clip. This also will set the rate, but without changing
   // the length of the clip
   void Resample(int rate, BasicUI::ProgressDialog *progress = nullptr);
 
   double GetSequenceStartTime() const noexcept;
   void SetSequenceStartTime(double startTime);
   double GetSequenceEndTime() const;
   sampleCount GetSequenceStartSample() const;
   sampleCount GetSequenceSamplesCount() const;
 
   double GetPlayStartTime() const noexcept override;
   void SetPlayStartTime(double time);
 
   double GetPlayEndTime() const override;
 
   double GetPlayDuration() const;
 
   bool IsEmpty() const;
 
   sampleCount GetPlayStartSample() const;
   sampleCount GetPlayEndSample() const;
 
   sampleCount GetVisibleSampleCount() const override;
 
   void SetTrimLeft(double trim);
   double GetTrimLeft() const noexcept;
 
   void SetTrimRight(double trim);
   double GetTrimRight() const noexcept;
 
   void TrimLeft(double deltaTime);
   void TrimRight(double deltaTime);
   void TrimQuarternotesFromRight(double quarters);
 
   void TrimLeftTo(double to);
   void TrimRightTo(double to);
 
   void ShiftBy(double delta) noexcept;
 
 
   bool SplitsPlayRegion(double t) const;
   bool WithinPlayRegion(double t) const;
   bool BeforePlayRegion(double t) const;
   bool AtOrBeforePlayRegion(double t) const;
   bool AfterPlayRegion(double t) const;
   bool EntirelyWithinPlayRegion(double t0, double t1) const;
   bool PartlyWithinPlayRegion(double t0, double t1) const;
   bool IntersectsPlayRegion(double t0, double t1) const;
   bool CoversEntirePlayRegion(double t0, double t1) const;
 
   sampleCount CountSamples(double t0, double t1) const;
 
   AudioSegmentSampleView GetSampleView(
      size_t iChannel, sampleCount start, size_t length,
      bool mayThrow = true) const override;
 
   AudioSegmentSampleView GetSampleView(
      size_t iChannel, double t0, double t1, bool mayThrow = true) const;
 
 
   bool GetSamples(size_t ii, samplePtr buffer, sampleFormat format,
                   sampleCount start, size_t len, bool mayThrow = true) const;
 
 
   bool GetSamples(samplePtr buffers[], sampleFormat format,
                   sampleCount start, size_t len, bool mayThrow = true) const;
 
 
   void SetSamples(size_t ii, constSamplePtr buffer, sampleFormat format,
      sampleCount start, size_t len,
      sampleFormat effectiveFormat 
   );
 
 
   Envelope &GetEnvelope() noexcept { return *mEnvelope; }
   const Envelope &GetEnvelope() const noexcept { return *mEnvelope; }
 
   void SetEnvelope(std::unique_ptr<Envelope> p);
 
 
   const BlockArray* GetSequenceBlockArray(size_t ii) const;
 
 
   Sequence* GetSequence(size_t ii) {
      assert(ii < NChannels());
      return mSequences[ii].get();
   }
   const Sequence* GetSequence(size_t ii) const { return mSequences[ii].get(); }
 
   std::pair<float, float> GetMinMax(size_t ii,
      double t0, double t1, bool mayThrow) const;
   float GetRMS(size_t ii, double t0, double t1, bool mayThrow) const;
 
   void UpdateEnvelopeTrackLen();
 
   std::shared_ptr<SampleBlock>
   AppendToChannel(size_t iChannel,
      constSamplePtr buffer, sampleFormat format, size_t len);
 
   std::shared_ptr<SampleBlock>
   AppendLegacyNewBlock(constSamplePtr buffer, sampleFormat format, size_t len);
 
 
   void AppendLegacySharedBlock(const std::shared_ptr<SampleBlock> &pBlock);
 
 
   bool Append(size_t iChannel, size_t nChannels,
      constSamplePtr buffers[], sampleFormat format,
      size_t len, unsigned int stride,
      sampleFormat effectiveFormat 
   );
 
 
   bool Append(constSamplePtr buffers[], sampleFormat format,
      size_t len, unsigned int stride,
      sampleFormat effectiveFormat 
   );
 
 
   void Flush();
 
   void RepairChannels();
 
   void Clear(double t0, double t1);
 
   void ClearLeft(double t);
   void ClearRight(double t);
 
 
   void ClearAndAddCutLine(double t0, double t1);
 
   void AddCutLine(WaveClipHolder pClip);
 
   bool Paste(double t0, const WaveClip& other);
 
 
   void InsertSilence( double t, double len, double *pEnvelopeValue = nullptr );
 
   void AppendSilence( double len, double envelopeValue );
 
   const WaveClipHolders &GetCutLines() { return mCutLines; }
   const WaveClipConstHolders &GetCutLines() const
      { return reinterpret_cast< const WaveClipConstHolders& >( mCutLines ); }
   size_t NumCutLines() const { return mCutLines.size(); }
 
   bool FindCutLine(double cutLinePosition,
      double* cutLineStart = nullptr,
      double *cutLineEnd = nullptr) const;
 
   void ExpandCutLine(double cutLinePosition);
 
   bool RemoveCutLine(double cutLinePosition);
 
   void OffsetCutLines(double t0, double len);
 
 
   void CloseLock() noexcept;
 
   //
   // 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(size_t ii, XMLWriter &xmlFile) const;
 
   // AWD, Oct 2009: for pasting whitespace at the end of selection
   bool GetIsPlaceholder() const { return mIsPlaceholder; }
   void SetIsPlaceholder(bool val) { mIsPlaceholder = val; }
 
   void SetName(const wxString& name);
   const wxString& GetName() const;
 
   // TimeToSamples and SamplesToTime take clip stretch ratio into account.
   // Use them to convert time / sample offsets.
   sampleCount TimeToSamples(double time) const override;
   double SamplesToTime(sampleCount s) const noexcept;
 
 
   void SetSilence(sampleCount offset, sampleCount length);
 
 
   constSamplePtr GetAppendBuffer(size_t ii) const;
   size_t GetAppendBufferLen(size_t ii) const;
 
   void
   OnProjectTempoChange(const std::optional<double>& oldTempo, double newTempo);
 
   SampleFormats GetSampleFormats() const;
 
   size_t CountBlocks() const;
 
 
   void DiscardRightChannel();
 
   void SwapChannels();
 
 
   std::shared_ptr<WaveClip> SplitChannels();
 
 
   void MakeStereo(WaveClip &&other, bool mustAlign);
 
   // These return a nonnegative number of samples meant to size a memory buffer
   size_t GetBestBlockSize(sampleCount t) const;
   size_t GetMaxBlockSize() const;
 
 
   WaveClip(const WaveClip& orig,
            const SampleBlockFactoryPtr &factory,
            bool copyCutlines, CreateToken token);
 
private:
   static void TransferSequence(WaveClip &origClip, WaveClip &newClip);
   static void FixSplitCutlines(
      WaveClipHolders &myCutlines, WaveClipHolders &newCutlines);
 
   size_t GreatestAppendBufferLen() const;
 
 
   void MarkChanged() noexcept;
 
   // Always gives non-negative answer, not more than sample sequence length
   // even if t0 really falls outside that range
   sampleCount TimeToSequenceSamples(double t) const;
   bool StretchRatioEquals(double value) const;
   sampleCount GetNumSamples() const;
   const SampleBlockFactoryPtr &GetFactory() const;
   std::vector<std::unique_ptr<Sequence>> GetEmptySequenceCopies() const;
   void StretchCutLines(double ratioChange);
   double SnapToTrackSample(double time) const noexcept;
 
 
   class ClearSequenceFinisher {
   public:
      ClearSequenceFinisher() noexcept = default;
      /*
       @param t0 start of deleted range
       @param t1 end of deleted range
       @param clip_t0 t0 clamped to previous play region
       @param clip_t1 t1 clamped to previous play region
       */
      ClearSequenceFinisher(WaveClip *pClip,
         double t0, double t1, double clip_t0, double clip_t1) noexcept
         : pClip{ pClip }
         , t0{ t0 }, t1{ t1 }, clip_t0{ clip_t0 }, clip_t1{ clip_t1 }
      {}
      ClearSequenceFinisher &operator =(ClearSequenceFinisher &&other)
      {
         *this = other;
         other.pClip = nullptr;
         return *this;
      }
      ~ClearSequenceFinisher() noexcept;
      void Commit() noexcept { committed = true; }
 
   private:
      ClearSequenceFinisher&
         operator =(const ClearSequenceFinisher &other) = default;
      WaveClip *pClip{};
      double t0{}, t1{}, clip_t0{}, clip_t1{};
      bool committed = false;
   };
 
 
   [[nodiscard]] ClearSequenceFinisher ClearSequence(double t0, double t1);
 
   struct Transaction {
      explicit Transaction(WaveClip &clip);
      ~Transaction();
      void Commit() { committed = true; }
 
      WaveClip &clip;
      std::vector<std::unique_ptr<Sequence>> sequences;
      const double mTrimLeft,
         mTrimRight;
      bool committed{ false };
   };
 
   double mSequenceOffset { 0 };
   double mTrimLeft { 0 };
   double mTrimRight { 0 };
 
   PitchAndSpeedPreset mPitchAndSpeedPreset { PitchAndSpeedPreset::Default };
   int mCentShift { 0 };
 
   // Used in GetStretchRatio which computes the factor, by which the sample
   // interval is multiplied, to get a realtime duration.
   double mClipStretchRatio = 1.;
   std::optional<double> mRawAudioTempo;
   std::optional<double> mProjectTempo;
 
   int mRate;
 
   std::vector<std::unique_ptr<Sequence>> mSequences;
   std::unique_ptr<Envelope> mEnvelope;
 
 
   WaveClipHolders mCutLines {};
 
   // AWD, Oct. 2009: for whitespace-at-end-of-selection pasting
   bool mIsPlaceholder { false };
 
   wxString mName;
};
 
#endif