rtaglib 0.2.3 → 0.3.0

data/ext/taglib/taglib-mswin32/include/taglib/oggpage.h

@@ -0,0 +1,203 @@
+/***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_OGGPAGE_H
+#define TAGLIB_OGGPAGE_H
+
+#include "taglib_export.h"
+#include "tbytevectorlist.h"
+
+namespace TagLib {
+
+  namespace Ogg {
+
+    class File;
+    class PageHeader;
+
+    //! An implementation of Ogg pages
+
+    /*!
+     * This is an implementation of the pages that make up an Ogg stream.
+     * This handles parsing pages and breaking them down into packets and handles
+     * the details of packets spanning multiple pages and pages that contiain
+     * multiple packets.
+     *
+     * In most Xiph.org formats the comments are found in the first few packets,
+     * this however is a reasonably complete implementation of Ogg pages that
+     * could potentially be useful for non-meta data purposes.
+     */
+
+    class TAGLIB_EXPORT Page
+    {
+    public:
+      /*!
+       * Read an Ogg page from the \a file at the position \a pageOffset.
+       */
+      Page(File *file, long pageOffset);
+
+      virtual ~Page();
+
+      /*!
+       * Returns the page's position within the file (in bytes).
+       */
+      long fileOffset() const;
+
+      /*!
+       * Returns a pointer to the header for this page.  This pointer will become
+       * invalid when the page is deleted.
+       */
+      const PageHeader *header() const;
+
+      /*!
+       * Returns the index of the first packet wholly or partially contained in
+       * this page.
+       *
+       * \see setFirstPacketIndex()
+       */
+      int firstPacketIndex() const;
+
+      /*!
+       * Sets the index of the first packet in the page.
+       *
+       * \see firstPacketIndex()
+       */
+      void setFirstPacketIndex(int index);
+
+      /*!
+       * When checking to see if a page contains a given packet this set of flags
+       * represents the possible values for that packets status in the page.
+       *
+       * \see containsPacket()
+       */
+      enum ContainsPacketFlags {
+        //! No part of the packet is contained in the page
+        DoesNotContainPacket = 0x0000,
+        //! The packet is wholly contained in the page
+        CompletePacket       = 0x0001,
+        //! The page starts with the given packet
+        BeginsWithPacket     = 0x0002,
+        //! The page ends with the given packet
+        EndsWithPacket       = 0x0004
+      };
+
+      /*!
+       * Checks to see if the specified \a packet is contained in the current
+       * page.
+       *
+       * \see ContainsPacketFlags
+       */
+      ContainsPacketFlags containsPacket(int index) const;
+
+      /*!
+       * Returns the number of packets (whole or partial) in this page.
+       */
+      uint packetCount() const;
+
+      /*!
+       * Returns a list of the packets in this page.
+       *
+       * \note Either or both the first and last packets may be only partial.
+       * \see PageHeader::firstPacketContinued()
+       */
+      ByteVectorList packets() const;
+
+      /*!
+       * Returns the size of the page in bytes.
+       */
+      int size() const;
+
+      ByteVector render() const;
+
+      /*!
+       * Defines a strategy for pagination, or grouping pages into Ogg packets,
+       * for use with pagination methods.
+       *
+       * \note Yes, I'm aware that this is not a canonical "Strategy Pattern",
+       * the term was simply convenient.
+       */
+      enum PaginationStrategy {
+        /*!
+         * Attempt to put the specified set of packets into a single Ogg packet.
+         * If the sum of the packet data is greater than will fit into a single
+         * Ogg page -- 65280 bytes -- this will fall back to repagination using
+         * the recommended page sizes.
+         */
+        SinglePagePerGroup,
+        /*!
+         * Split the packet or group of packets into pages that conform to the
+         * sizes recommended in the Ogg standard.
+         */
+        Repaginate
+      };
+
+      /*!
+       * Pack \a packets into Ogg pages using the \a strategy for pagination.
+       * The page number indicater inside of the rendered packets will start
+       * with \a firstPage and be incremented for each page rendered.
+       * \a containsLastPacket should be set to true if \a packets contains the
+       * last page in the stream and will set the appropriate flag in the last
+       * rendered Ogg page's header.  \a streamSerialNumber should be set to
+       * the serial number for this stream.
+       *
+       * \note The "absolute granule position" is currently always zeroed using
+       * this method as this suffices for the comment headers.
+       *
+       * \warning The pages returned by this method must be deleted by the user.
+       * You can use List<T>::setAutoDelete(true) to set these pages to be
+       * automatically deleted when this list passes out of scope.
+       *
+       * \see PaginationStrategy
+       * \see List::setAutoDelete()
+       */
+      static List<Page *> paginate(const ByteVectorList &packets,
+                                   PaginationStrategy strategy,
+                                   uint streamSerialNumber,
+                                   int firstPage,
+                                   bool firstPacketContinued = false,
+                                   bool lastPacketCompleted = true,
+                                   bool containsLastPacket = false);
+
+    protected:
+      /*!
+       * Creates an Ogg packet based on the data in \a packets.  The page number
+       * for each page will be set to \a pageNumber.
+       */
+      Page(const ByteVectorList &packets,
+           uint streamSerialNumber,
+           int pageNumber,
+           bool firstPacketContinued = false,
+           bool lastPacketCompleted = true,
+           bool containsLastPacket = false);
+
+    private:
+      Page(const Page &);
+      Page &operator=(const Page &);
+
+      class PagePrivate;
+      PagePrivate *d;
+    };
+  }
+}
+#endif

data/ext/taglib/taglib-mswin32/include/taglib/oggpageheader.h

@@ -0,0 +1,232 @@
+/***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_OGGPAGEHEADER_H
+#define TAGLIB_OGGPAGEHEADER_H
+
+#include "tlist.h"
+#include "tbytevector.h"
+#include "taglib_export.h"
+
+namespace TagLib {
+
+  namespace Ogg {
+
+    class File;
+
+    //! An implementation of the page headers associated with each Ogg::Page
+
+    /*!
+     * This class implements Ogg page headers which contain the information
+     * about Ogg pages needed to break them into packets which can be passed on
+     * to the codecs.
+     */
+
+    class TAGLIB_EXPORT PageHeader
+    {
+    public:
+      /*!
+       * Reads a PageHeader from \a file starting at \a pageOffset.  The defaults
+       * create a page with no (and as such, invalid) data that must be set
+       * later.
+       */
+      PageHeader(File *file = 0, long pageOffset = -1);
+
+      /*!
+       * Deletes this instance of the PageHeader.
+       */
+      virtual ~PageHeader();
+
+      /*!
+       * Returns true if the header parsed properly and is valid.
+       */
+      bool isValid() const;
+
+      /*!
+       * Ogg pages contain a list of packets (which are used by the contained
+       * codecs).  The sizes of these pages is encoded in the page header.  This
+       * returns a list of the packet sizes in bytes.
+       *
+       * \see setPacketSizes()
+       */
+      List<int> packetSizes() const;
+
+      /*!
+       * Sets the sizes of the packets in this page to \a sizes.  Internally this
+       * updates the lacing values in the header.
+       *
+       * \see packetSizes()
+       */
+      void setPacketSizes(const List<int> &sizes);
+
+      /*!
+       * Some packets can be <i>continued</i> across multiple pages.  If the
+       * first packet in the current page is a continuation this will return
+       * true.  If this is page starts with a new packet this will return false.
+       *
+       * \see lastPacketCompleted()
+       * \see setFirstPacketContinued()
+       */
+      bool firstPacketContinued() const;
+
+      /*!
+       * Sets the internal flag indicating if the first packet in this page is
+       * continued to \a continued.
+       *
+       * \see firstPacketContinued()
+       */
+      void setFirstPacketContinued(bool continued);
+
+      /*!
+       * Returns true if the last packet of this page is completely contained in
+       * this page.
+       *
+       * \see firstPacketContinued()
+       * \see setLastPacketCompleted()
+       */
+      bool lastPacketCompleted() const;
+
+      /*!
+       * Sets the internal flag indicating if the last packet in this page is
+       * complete to \a completed.
+       *
+       * \see lastPacketCompleted()
+       */
+      void setLastPacketCompleted(bool completed);
+
+      /*!
+       * This returns true if this is the first page of the Ogg (logical) stream.
+       *
+       * \see setFirstPageOfStream()
+       */
+      bool firstPageOfStream() const;
+
+      /*!
+       * Marks this page as the first page of the Ogg stream.
+       *
+       * \see firstPageOfStream()
+       */
+      void setFirstPageOfStream(bool first);
+
+      /*!
+       * This returns true if this is the last page of the Ogg (logical) stream.
+       *
+       * \see setLastPageOfStream()
+       */
+      bool lastPageOfStream() const;
+
+      /*!
+       * Marks this page as the last page of the Ogg stream.
+       *
+       * \see lastPageOfStream()
+       */
+      void setLastPageOfStream(bool last);
+
+      /*!
+       * A special value of containing the position of the packet to be
+       * interpreted by the codec.  In the case of Vorbis this contains the PCM
+       * value and is used to calculate the length of the stream.
+       *
+       * \see setAbsoluteGranularPosition()
+       */
+      long long absoluteGranularPosition() const;
+
+      /*!
+       * A special value of containing the position of the packet to be
+       * interpreted by the codec.  It is only supported here so that it may be
+       * coppied from one page to another.
+       *
+       * \see absoluteGranularPosition()
+       */
+      void setAbsoluteGranularPosition(long long agp);
+
+      /*!
+       * Every Ogg logical stream is given a random serial number which is common
+       * to every page in that logical stream.  This returns the serial number of
+       * the stream associated with this packet.
+       *
+       * \see setStreamSerialNumber()
+       */
+      uint streamSerialNumber() const;
+
+      /*!
+       * Every Ogg logical stream is given a random serial number which is common
+       * to every page in that logical stream.  This sets this pages serial
+       * number.  This method should be used when adding new pages to a logical
+       * stream.
+       *
+       * \see streamSerialNumber()
+       */
+      void setStreamSerialNumber(uint n);
+
+      /*!
+       * Returns the index of the page within the Ogg stream.  This helps make it
+       * possible to determine if pages have been lost.
+       *
+       * \see setPageSequenceNumber()
+       */
+      int pageSequenceNumber() const;
+
+      /*!
+       * Sets the page's position in the stream to \a sequenceNumber.
+       *
+       * \see pageSequenceNumber()
+       */
+      void setPageSequenceNumber(int sequenceNumber);
+
+      /*!
+       * Returns the complete header size.
+       */
+      int size() const;
+
+      /*!
+       * Returns the size of the data portion of the page -- i.e. the size of the
+       * page less the header size.
+       */
+      int dataSize() const;
+
+      /*!
+       * Render the page header to binary data.
+       *
+       * \note The checksum -- bytes 22 - 25 -- will be left empty and must be
+       * filled in when rendering the entire page.
+       */
+      ByteVector render() const;
+
+    private:
+      PageHeader(const PageHeader &);
+      PageHeader &operator=(const PageHeader &);
+
+      void read();
+      ByteVector lacingValues() const;
+
+      class PageHeaderPrivate;
+      PageHeaderPrivate *d;
+    };
+
+  }
+}
+
+#endif

data/ext/taglib/taglib-mswin32/include/taglib/relativevolumeframe.h

@@ -0,0 +1,274 @@
+/***************************************************************************
+    copyright            : (C) 2002 - 2008 by Scott Wheeler
+    email                : wheeler@kde.org
+ ***************************************************************************/
+
+/***************************************************************************
+ *   This library is free software; you can redistribute it and/or modify  *
+ *   it under the terms of the GNU Lesser General Public License version   *
+ *   2.1 as published by the Free Software Foundation.                     *
+ *                                                                         *
+ *   This library is distributed in the hope that it will be useful, but   *
+ *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *   Lesser General Public License for more details.                       *
+ *                                                                         *
+ *   You should have received a copy of the GNU Lesser General Public      *
+ *   License along with this library; if not, write to the Free Software   *
+ *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+ *   USA                                                                   *
+ *                                                                         *
+ *   Alternatively, this file is available under the Mozilla Public        *
+ *   License Version 1.1.  You may obtain a copy of the License at         *
+ *   http://www.mozilla.org/MPL/                                           *
+ ***************************************************************************/
+
+#ifndef TAGLIB_RELATIVEVOLUMEFRAME_H
+#define TAGLIB_RELATIVEVOLUMEFRAME_H
+
+#include <tlist.h>
+#include <id3v2frame.h>
+#include "taglib_export.h"
+
+namespace TagLib {
+
+  namespace ID3v2 {
+
+    //! An ID3v2 relative volume adjustment frame implementation
+
+    /*!
+     * This is an implementation of ID3v2 relative volume adjustment.  The
+     * presence of this frame makes it possible to specify an increase in volume
+     * for an audio file or specific audio tracks in that file.
+     *
+     * Multiple relative volume adjustment frames may be present in the tag
+     * each with a unique identification and describing volume adjustment for
+     * different channel types.
+     */
+
+    class TAGLIB_EXPORT RelativeVolumeFrame : public Frame
+    {
+      friend class FrameFactory;
+
+    public:
+
+      /*!
+       * This indicates the type of volume adjustment that should be applied.
+       */
+      enum ChannelType {
+        //! A type not enumerated below
+        Other        = 0x00,
+        //! The master volume for the track
+        MasterVolume = 0x01,
+        //! The front right audio channel
+        FrontRight   = 0x02,
+        //! The front left audio channel
+        FrontLeft    = 0x03,
+        //! The back right audio channel
+        BackRight    = 0x04,
+        //! The back left audio channel
+        BackLeft     = 0x05,
+        //! The front center audio channel
+        FrontCentre  = 0x06,
+        //! The back center audio channel
+        BackCentre   = 0x07,
+        //! The subwoofer audio channel
+        Subwoofer    = 0x08
+      };
+
+      //! Struct that stores the relevant values for ID3v2 peak volume
+
+      /*!
+       * The peak volume is described as a series of bits that is padded to fill
+       * a block of bytes.  These two values should always be updated in tandem.
+       */
+      struct PeakVolume
+      {
+        /*!
+         * Constructs an empty peak volume description.
+         */
+        PeakVolume() : bitsRepresentingPeak(0) {}
+        /*!
+         * The number of bits (in the range of 0 to 255) used to describe the
+         * peak volume.
+         */
+        unsigned char bitsRepresentingPeak;
+        /*!
+         * The array of bits (represented as a series of bytes) used to describe
+         * the peak volume.
+         */
+        ByteVector peakVolume;
+      };
+
+      /*!
+       * Constructs a RelativeVolumeFrame.  The relevant data should be set
+       * manually.
+       */
+      RelativeVolumeFrame();
+
+      /*!
+       * Constructs a RelativeVolumeFrame based on the contents of \a data.
+       */
+      RelativeVolumeFrame(const ByteVector &data);
+
+      /*!
+       * Destroys the RelativeVolumeFrame instance.
+       */
+      virtual ~RelativeVolumeFrame();
+
+      /*!
+       * Returns the frame's identification.
+       *
+       * \see identification()
+       */
+      virtual String toString() const;
+
+      /*!
+       * Returns a list of channels with information currently in the frame.
+       */
+      List<ChannelType> channels() const;
+
+      /*!
+       * \deprecated Always returns master volume.
+       */
+      ChannelType channelType() const;
+
+      /*!
+       * \deprecated This method no longer has any effect.
+       */
+      void setChannelType(ChannelType t);
+
+      /*
+       * There was a terrible API goof here, and while this can't be changed to
+       * the way it appears below for binary compaibility reasons, let's at
+       * least pretend that it looks clean.
+       */
+
+#ifdef DOXYGEN
+
+      /*!
+       * Returns the relative volume adjustment "index".  As indicated by the
+       * ID3v2 standard this is a 16-bit signed integer that reflects the
+       * decibils of adjustment when divided by 512.
+       *
+       * This defaults to returning the value for the master volume channel if
+       * available and returns 0 if the specified channel does not exist.
+       *
+       * \see setVolumeAdjustmentIndex()
+       * \see volumeAjustment()
+       */
+      short volumeAdjustmentIndex(ChannelType type = MasterVolume) const;
+
+      /*!
+       * Set the volume adjustment to \a index.  As indicated by the ID3v2
+       * standard this is a 16-bit signed integer that reflects the decibils of
+       * adjustment when divided by 512.
+       *
+       * By default this sets the value for the master volume.
+       *
+       * \see volumeAdjustmentIndex()
+       * \see setVolumeAjustment()
+       */
+      void setVolumeAdjustmentIndex(short index, ChannelType type = MasterVolume);
+
+      /*!
+       * Returns the relative volume adjustment in decibels.
+       *
+       * \note Because this is actually stored internally as an "index" to this
+       * value the value returned by this method may not be identical to the
+       * value set using setVolumeAdjustment().
+       *
+       * This defaults to returning the value for the master volume channel if
+       * available and returns 0 if the specified channel does not exist.
+       *
+       * \see setVolumeAdjustment()
+       * \see volumeAdjustmentIndex()
+       */
+      float volumeAdjustment(ChannelType type = MasterVolume) const;
+
+      /*!
+       * Set the relative volume adjustment in decibels to \a adjustment.
+       *
+       * By default this sets the value for the master volume.
+       *
+       * \note Because this is actually stored internally as an "index" to this
+       * value the value set by this method may not be identical to the one
+       * returned by volumeAdjustment().
+       *
+       * \see setVolumeAdjustment()
+       * \see volumeAdjustmentIndex()
+       */
+      void setVolumeAdjustment(float adjustment, ChannelType type = MasterVolume);
+
+      /*!
+       * Returns the peak volume (represented as a length and a string of bits).
+       *
+       * This defaults to returning the value for the master volume channel if
+       * available and returns 0 if the specified channel does not exist.
+       *
+       * \see setPeakVolume()
+       */
+      PeakVolume peakVolume(ChannelType type = MasterVolume) const;
+
+      /*!
+       * Sets the peak volume to \a peak.
+       *
+       * By default this sets the value for the master volume.
+       *
+       * \see peakVolume()
+       */
+      void setPeakVolume(const PeakVolume &peak, ChannelType type = MasterVolume);
+
+#else
+
+      // BIC: Combine each of the following pairs of functions (or maybe just
+      // rework this junk altogether).
+
+      short volumeAdjustmentIndex(ChannelType type) const;
+      short volumeAdjustmentIndex() const;
+
+      void setVolumeAdjustmentIndex(short index, ChannelType type);
+      void setVolumeAdjustmentIndex(short index);
+
+      float volumeAdjustment(ChannelType type) const;
+      float volumeAdjustment() const;
+
+      void setVolumeAdjustment(float adjustment, ChannelType type);
+      void setVolumeAdjustment(float adjustment);
+
+      PeakVolume peakVolume(ChannelType type) const;
+      PeakVolume peakVolume() const;
+
+      void setPeakVolume(const PeakVolume &peak, ChannelType type);
+      void setPeakVolume(const PeakVolume &peak);
+
+#endif
+
+      /*!
+       * Returns the identification for this frame.
+       */
+      String identification() const;
+
+      /*!
+       * Sets the identification of the frame to \a s. The string
+       * is used to identify the situation and/or device where this
+       * adjustment should apply.
+       */
+      void setIdentification(const String &s);
+
+    protected:
+      virtual void parseFields(const ByteVector &data);
+      virtual ByteVector renderFields() const;
+
+    private:
+      RelativeVolumeFrame(const ByteVector &data, Header *h);
+      RelativeVolumeFrame(const RelativeVolumeFrame &);
+      RelativeVolumeFrame &operator=(const RelativeVolumeFrame &);
+
+      class RelativeVolumeFramePrivate;
+      RelativeVolumeFramePrivate *d;
+    };
+
+  }
+}
+#endif