juce_AudioPlayHead.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   The code included in this file is provided under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license. Permission
   To use, copy, modify, and/or distribute this software for any purpose with or
   without fee is hereby granted provided that the above copyright notice and
   this permission notice appear in all copies.
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  AudioPlayHead
{
protected:
    //==============================================================================
    AudioPlayHead() = default;
 
public:
    virtual ~AudioPlayHead() = default;
 
    //==============================================================================
    enum FrameRateType
    {
        fps23976        = 0,
        fps24           = 1,
        fps25           = 2,
        fps2997         = 3,
        fps30           = 4,
        fps2997drop     = 5,
        fps30drop       = 6,
        fps60           = 7,
        fps60drop       = 8,
        fpsUnknown      = 99
    };

    class JUCE_API  FrameRate
    {
    public:
        FrameRate() = default;

        FrameRate (FrameRateType type) : FrameRate (fromType (type)) {}

        FrameRateType getType() const
        {
            switch (base)
            {
                case 24:    return pulldown ? fps23976 : fps24;
                case 25:    return fps25;
                case 30:    return pulldown ? (drop ? fps2997drop : fps2997)
                                            : (drop ? fps30drop   : fps30);
                case 60:    return drop ? fps60drop : fps60;
            }
 
            return fpsUnknown;
        }

        int getBaseRate() const                         { return base; }

        bool isDrop() const                             { return drop; }

        bool isPullDown() const                         { return pulldown; }

        double getEffectiveRate() const                 { return pulldown ? (double) base / 1.001 : (double) base; }

        JUCE_NODISCARD FrameRate withBaseRate (int x) const            { return with (&FrameRate::base, x); }

        JUCE_NODISCARD FrameRate withDrop (bool x = true) const        { return with (&FrameRate::drop, x); }

        JUCE_NODISCARD FrameRate withPullDown (bool x = true) const    { return with (&FrameRate::pulldown, x); }

        bool operator== (const FrameRate& other) const
        {
            const auto tie = [] (const FrameRate& x) { return std::tie (x.base, x.drop, x.pulldown); };
            return tie (*this) == tie (other);
        }

        bool operator!= (const FrameRate& other) const { return ! (*this == other); }
 
    private:
        static FrameRate fromType (FrameRateType type)
        {
            switch (type)
            {
                case fps23976:      return FrameRate().withBaseRate (24).withPullDown();
                case fps24:         return FrameRate().withBaseRate (24);
                case fps25:         return FrameRate().withBaseRate (25);
                case fps2997:       return FrameRate().withBaseRate (30).withPullDown();
                case fps30:         return FrameRate().withBaseRate (30);
                case fps2997drop:   return FrameRate().withBaseRate (30).withDrop().withPullDown();
                case fps30drop:     return FrameRate().withBaseRate (30).withDrop();
                case fps60:         return FrameRate().withBaseRate (60);
                case fps60drop:     return FrameRate().withBaseRate (60).withDrop();
                case fpsUnknown:    break;
            }
 
            return {};
        }
 
        template <typename Member, typename Value>
        FrameRate with (Member&& member, Value&& value) const
        {
            auto copy = *this;
            copy.*member = std::forward<Value> (value);
            return copy;
        }
 
        int base = 0;
        bool drop = false, pulldown = false;
    };

    struct JUCE_API TimeSignature
    {
        int numerator   = 4;

        int denominator = 4;
 
        bool operator== (const TimeSignature& other) const
        {
            const auto tie = [] (auto& x) { return std::tie (x.numerator, x.denominator); };
            return tie (*this) == tie (other);
        }
 
        bool operator!= (const TimeSignature& other) const
        {
            return ! operator== (other);
        }
    };

    struct JUCE_API LoopPoints
    {
        double ppqStart = 0;

        double ppqEnd = 0;
 
        bool operator== (const LoopPoints& other) const
        {
            const auto tie = [] (auto& x) { return std::tie (x.ppqStart, x.ppqEnd); };
            return tie (*this) == tie (other);
        }
 
        bool operator!= (const LoopPoints& other) const
        {
            return ! operator== (other);
        }
    };
 
    //==============================================================================
    struct JUCE_API  CurrentPositionInfo
    {
        double bpm = 120.0;

        int timeSigNumerator = 4;

        int timeSigDenominator = 4;

        int64 timeInSamples = 0;
        double timeInSeconds = 0;

        double editOriginTime = 0;

        double ppqPosition = 0;

        double ppqPositionOfLastBarStart = 0;

        FrameRate frameRate = FrameRateType::fps23976;

        bool isPlaying = false;

        bool isRecording = false;

        double ppqLoopStart = 0;

        double ppqLoopEnd = 0;

        bool isLooping = false;
 
        //==============================================================================
        bool operator== (const CurrentPositionInfo& other) const noexcept
        {
            const auto tie = [] (const CurrentPositionInfo& i)
            {
                return std::tie (i.timeInSamples,
                                 i.ppqPosition,
                                 i.editOriginTime,
                                 i.ppqPositionOfLastBarStart,
                                 i.frameRate,
                                 i.isPlaying,
                                 i.isRecording,
                                 i.bpm,
                                 i.timeSigNumerator,
                                 i.timeSigDenominator,
                                 i.ppqLoopStart,
                                 i.ppqLoopEnd,
                                 i.isLooping);
            };
 
            return tie (*this) == tie (other);
        }
 
        bool operator!= (const CurrentPositionInfo& other) const noexcept
        {
            return ! operator== (other);
        }
 
        void resetToDefault()
        {
            *this = CurrentPositionInfo{};
        }
    };
 
    //==============================================================================
    class PositionInfo
    {
    public:
        Optional<int64_t> getTimeInSamples() const                      { return getOptional (flagTimeSamples, timeInSamples); }

        void setTimeInSamples (Optional<int64_t> timeInSamplesIn)       {        setOptional (flagTimeSamples, timeInSamples, timeInSamplesIn); }

        Optional<double> getTimeInSeconds() const                       { return getOptional (flagTimeSeconds, timeInSeconds); }

        void setTimeInSeconds (Optional<double> timeInSecondsIn)        {        setOptional (flagTimeSeconds, timeInSeconds, timeInSecondsIn); }

        Optional<double> getBpm() const                                 { return getOptional (flagTempo, tempoBpm); }

        void setBpm (Optional<double> bpmIn)                            {        setOptional (flagTempo, tempoBpm, bpmIn); }

        Optional<TimeSignature> getTimeSignature() const                { return getOptional (flagTimeSignature, timeSignature); }

        void setTimeSignature (Optional<TimeSignature> timeSignatureIn) {        setOptional (flagTimeSignature, timeSignature, timeSignatureIn); }

        Optional<LoopPoints> getLoopPoints() const                      { return getOptional (flagLoopPoints, loopPoints); }

        void setLoopPoints (Optional<LoopPoints> loopPointsIn)          {        setOptional (flagLoopPoints, loopPoints, loopPointsIn); }

        Optional<int64_t> getBarCount() const                           { return getOptional (flagBarCount, barCount); }

        void setBarCount (Optional<int64_t> barCountIn)                 {        setOptional (flagBarCount, barCount, barCountIn); }

        Optional<double> getPpqPositionOfLastBarStart() const           { return getOptional (flagLastBarStartPpq, lastBarStartPpq); }

        void setPpqPositionOfLastBarStart (Optional<double> positionIn) {        setOptional (flagLastBarStartPpq, lastBarStartPpq, positionIn); }

        Optional<FrameRate> getFrameRate() const                        { return getOptional (flagFrameRate, frame); }

        void setFrameRate (Optional<FrameRate> frameRateIn)             {        setOptional (flagFrameRate, frame, frameRateIn); }

        Optional<double> getPpqPosition() const                         { return getOptional (flagPpqPosition, positionPpq); }

        void setPpqPosition (Optional<double> ppqPositionIn)            {        setOptional (flagPpqPosition, positionPpq, ppqPositionIn); }

        Optional<double> getEditOriginTime() const                      { return getOptional (flagOriginTime, originTime); }

        void setEditOriginTime (Optional<double> editOriginTimeIn)      {        setOptional (flagOriginTime, originTime, editOriginTimeIn); }

        Optional<uint64_t> getHostTimeNs() const                        { return getOptional (flagHostTimeNs, hostTimeNs); }

        void setHostTimeNs (Optional<uint64_t> hostTimeNsIn)            {        setOptional (flagHostTimeNs, hostTimeNs, hostTimeNsIn); }

        bool getIsPlaying() const                                       { return getFlag (flagIsPlaying); }

        void setIsPlaying (bool isPlayingIn)                            {        setFlag (flagIsPlaying, isPlayingIn); }

        bool getIsRecording() const                                     { return getFlag (flagIsRecording); }

        void setIsRecording (bool isRecordingIn)                        {        setFlag (flagIsRecording, isRecordingIn); }

        bool getIsLooping() const                                       { return getFlag (flagIsLooping); }

        void setIsLooping (bool isLoopingIn)                            {        setFlag (flagIsLooping, isLoopingIn); }
 
        bool operator== (const PositionInfo& other) const noexcept
        {
            const auto tie = [] (const PositionInfo& i)
            {
                return std::make_tuple (i.getTimeInSamples(),
                                        i.getTimeInSeconds(),
                                        i.getPpqPosition(),
                                        i.getEditOriginTime(),
                                        i.getPpqPositionOfLastBarStart(),
                                        i.getFrameRate(),
                                        i.getBarCount(),
                                        i.getTimeSignature(),
                                        i.getBpm(),
                                        i.getLoopPoints(),
                                        i.getHostTimeNs(),
                                        i.getIsPlaying(),
                                        i.getIsRecording(),
                                        i.getIsLooping());
            };
 
            return tie (*this) == tie (other);
        }
 
        bool operator!= (const PositionInfo& other) const noexcept
        {
            return ! operator== (other);
        }
 
    private:
        bool getFlag (int64_t flagToCheck) const
        {
            return (flagToCheck & flags) != 0;
        }
 
        void setFlag (int64_t flagToCheck, bool value)
        {
            flags = (value ? flags | flagToCheck : flags & ~flagToCheck);
        }
 
        template <typename Value>
        Optional<Value> getOptional (int64_t flagToCheck, Value value) const
        {
            return getFlag (flagToCheck) ? makeOptional (std::move (value)) : nullopt;
        }
 
        template <typename Value>
        void setOptional (int64_t flagToCheck, Value& value, Optional<Value> opt)
        {
            if (opt.hasValue())
                value = *opt;
 
            setFlag (flagToCheck, opt.hasValue());
        }
 
        enum
        {
            flagTimeSignature   = 1 << 0,
            flagLoopPoints      = 1 << 1,
            flagFrameRate       = 1 << 2,
            flagTimeSeconds     = 1 << 3,
            flagLastBarStartPpq = 1 << 4,
            flagPpqPosition     = 1 << 5,
            flagOriginTime      = 1 << 6,
            flagTempo           = 1 << 7,
            flagTimeSamples     = 1 << 8,
            flagBarCount        = 1 << 9,
            flagHostTimeNs      = 1 << 10,
            flagIsPlaying       = 1 << 11,
            flagIsRecording     = 1 << 12,
            flagIsLooping       = 1 << 13
        };
 
        TimeSignature timeSignature;
        LoopPoints loopPoints;
        FrameRate frame        = FrameRateType::fps23976;
        double timeInSeconds   = 0.0;
        double lastBarStartPpq = 0.0;
        double positionPpq     = 0.0;
        double originTime      = 0.0;
        double tempoBpm        = 0.0;
        int64_t timeInSamples  = 0;
        int64_t barCount       = 0;
        uint64_t hostTimeNs    = 0;
        int64_t flags          = 0;
    };
 
    //==============================================================================
    [[deprecated ("Use getPosition instead. Not all hosts are able to provide all time position information; getPosition differentiates clearly between set and unset fields.")]]
    bool getCurrentPosition (CurrentPositionInfo& result)
    {
        if (const auto pos = getPosition())
        {
            result.resetToDefault();
 
            if (const auto sig = pos->getTimeSignature())
            {
                result.timeSigNumerator   = sig->numerator;
                result.timeSigDenominator = sig->denominator;
            }
 
            if (const auto loop = pos->getLoopPoints())
            {
                result.ppqLoopStart     = loop->ppqStart;
                result.ppqLoopEnd       = loop->ppqEnd;
            }
 
            if (const auto frame = pos->getFrameRate())
                result.frameRate = *frame;
 
            if (const auto timeInSeconds = pos->getTimeInSeconds())
                result.timeInSeconds = *timeInSeconds;
 
            if (const auto lastBarStartPpq = pos->getPpqPositionOfLastBarStart())
                result.ppqPositionOfLastBarStart = *lastBarStartPpq;
 
            if (const auto ppqPosition = pos->getPpqPosition())
                result.ppqPosition = *ppqPosition;
 
            if (const auto originTime = pos->getEditOriginTime())
                result.editOriginTime = *originTime;
 
            if (const auto bpm = pos->getBpm())
                result.bpm = *bpm;
 
            if (const auto timeInSamples = pos->getTimeInSamples())
                result.timeInSamples = *timeInSamples;
 
            result.isPlaying    = pos->getIsPlaying();
            result.isRecording  = pos->getIsRecording();
            result.isLooping    = pos->getIsLooping();
 
            return true;
        }
 
        return false;
    }

    virtual Optional<PositionInfo> getPosition() const = 0;

    virtual bool canControlTransport()                         { return false; }

    virtual void transportPlay (bool shouldStartPlaying)       { ignoreUnused (shouldStartPlaying); }

    virtual void transportRecord (bool shouldStartRecording)   { ignoreUnused (shouldStartRecording); }

    virtual void transportRewind()                             {}
};
 
} // namespace juce