src/AS_02_IAB.h

   1 /*
   2 Copyright (c), Bjoern Stresing, Patrick Bichiou, Wolfgang Ruppel,
   3 John Hurst, Pierre-Anthony Lemieux
   4
   5 All rights reserved.
   6
   7 Redistribution and use in source and binary forms, with or without
   8 modification, are permitted provided that the following conditions
   9 are met:
  10 1. Redistributions of source code must retain the above copyright
  11 notice, this list of conditions and the following disclaimer.
  12 2. Redistributions in binary form must reproduce the above copyright
  13 notice, this list of conditions and the following disclaimer in the
  14 documentation and/or other materials provided with the distribution.
  15 3. The name of the author may not be used to endorse or promote products
  16 derived from this software without specific prior written permission.
  17
  18 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 */
  29
  30 /**
  31  * Reader and writer classes for IAB Track Files, as defined in SMPTE ST 2067-201
  32  *
  33  * @file
  34  */
  35
  36 #ifndef AS_02_IAB_h__
  37 #define AS_02_IAB_h__
  38
  39 #include "AS_02.h"
  40 #include "AS_02_internal.h"
  41 #include "Metadata.h"
  42
  43 namespace AS_02 {
  44
  45   namespace IAB {
  46
  47     /**
  48      * Writes IAB Track Files as specified in ST SMPTE 2067-201
  49      *
  50      */
  51     class MXFWriter {
  52
  53       typedef h__AS02Writer<AS_02::MXF::AS02IndexWriterVBR> h__Writer;
  54
  55       ASDCP::mem_ptr<h__Writer> m_Writer;
  56       ui64_t m_ClipStart;
  57       WriterState_t m_State;
  58
  59       void Reset();
  60
  61       ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
  62
  63     public:
  64       MXFWriter();
  65       virtual ~MXFWriter();
  66
  67       /**
  68        * Must be preceded by a succesful OpenWrite() call followed by zero or more WriteFrame() calls
  69        *
  70        * Warning: direct manipulation of MXF structures can interfere
  71        * with the normal operation of the wrapper.  Caveat emptor!
  72        *
  73        * @return Header of the Track File
  74        *
  75        * @throws std::runtime_error if the Track File is not open
  76        */
  77       virtual const ASDCP::MXF::OP1aHeader& OP1aHeader() const;
  78
  79       /**
  80        * Must be preceded by a succesful OpenWrite() call followed by zero or more WriteFrame() calls
  81        *
  82        * Warning: direct manipulation of MXF structures can interfere
  83        * with the normal operation of the wrapper.  Caveat emptor!
  84        *
  85        * @return RIP of the Track File
  86        *
  87        * @throws std::runtime_error if the Track File is not open
  88        */
  89       virtual const ASDCP::MXF::RIP& RIP() const;
  90
  91       /**
  92        * Creates and prepares an IAB Track File for writing.
  93        *
  94        * Must be called following instantiation or after Finalize() call
  95        *
  96        * @param filename Path to the file. The file must no exist.
  97        * @param Info MXF file metadata to be written.
  98        * @param sub IAB Soundfield Subdescritor items to be written. MCATagName, MCATagSymbol, MCALabelDictionaryID, MCALinkID are ignored.
  99        * @param conformsToSpecs Value of the ConformsToSpecifications preface item
 100        * @param edit_rate Frame rate of the IA Bitstream
 101        * @param sampling_rate Sampling rate of the audio essence within the IA Bitstream
 102        *
 103        * @return RESULT_OK indicates that frames are ready to be written,
 104        * otherwise the reader is reset and the file is left is an undermined state.
 105        */
 106       Result_t OpenWrite(
 107         const std::string& filename,
 108         const ASDCP::WriterInfo& Info,
 109         const ASDCP::MXF::IABSoundfieldLabelSubDescriptor& sub,
 110         const std::vector<ASDCP::UL>& conformsToSpecs,
 111         const ASDCP::Rational& edit_rate,
 112         const ASDCP::Rational& sampling_rate = ASDCP::SampleRate_48k
 113       );
 114
 115         /**
 116          * Writes a single frame.
 117          *
 118          * Must be preceded by a succesful OpenWrite() call followed by zero or more WriteFrame() calls
 119          *
 120          * @param frame a complete IA Frame
 121          * @return RESULT_OK indicates that the frame is written and additional frames can be written,
 122          * otherwise the reader is reset and the file is left is an undermined state.
 123          */
 124       Result_t WriteFrame(const ASDCP::FrameBuffer& frame);
 125
 126
 127       /**
 128        * Writes an XML text document to the MXF file as per RP 2057. If the
 129        * optional AESEncContext argument is present, the document is encrypted
 130        * prior to writing. Fails if the file is not open, is finalized, or an
 131        * operating system error occurs.
 132        */
 133       Result_t AddDmsGenericPartUtf8Text(const ASDCP::FrameBuffer& frame_buffer, ASDCP::AESEncContext* enc = 0, ASDCP::HMACContext* hmac = 0,
 134                                          const std::string& trackDescription = "Descriptive Track", const std::string& dataDescription = "");
 135
 136       /**
 137        * Writes the Track File footer and closes the file.
 138        *
 139        * Must be preceded by a succesful OpenWrite() call followed by zero or more WriteFrame() calls
 140        *
 141        * @return RESULT_OK indicates that the frame is written and additional frames can be written,
 142        * otherwise the reader is reset and the file is left is an undermined state.
 143        */
 144       Result_t Finalize();
 145     };
 146
 147     /**
 148      * Reads IAB Track Files as specified in ST SMPTE 2067-201
 149      *
 150      */
 151     class MXFReader {
 152
 153       typedef h__AS02Reader h__Reader;
 154
 155       ASDCP::mem_ptr<h__Reader> m_Reader;
 156
 157       i64_t m_CurrentFrameIndex;
 158       std::vector<ui8_t> m_CurrentFrameBuffer;
 159       ReaderState_t m_State;
 160
 161       const Kumu::IFileReaderFactory& m_FileReaderFactory;
 162
 163       void Reset();
 164
 165       ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 166
 167     public:
 168
 169       /* typedefs*/
 170
 171       typedef std::pair<size_t, const ui8_t*> Frame;
 172
 173       /* methods */
 174
 175       /**
 176        * Construct MXF Reader
 177        * .
 178        * @param fileReaderFactory Abstract interface that allows
 179        * to override asdcplib's file read access by a user implementation.
 180        * Notice that the factory object reference needs to remain valid
 181        * when performing OpenRead operation.
 182        */
 183       MXFReader(const Kumu::IFileReaderFactory& fileReaderFactory);
 184
 185       virtual ~MXFReader();
 186
 187       /**
 188        * Warning: direct manipulation of MXF structures can interfere
 189        * with the normal operation of the wrapper.  Caveat emptor!
 190        *
 191        * @return Header of the Track File
 192        *
 193        * @throws std::runtime_error if the Track File is not open
 194        */
 195       virtual ASDCP::MXF::OP1aHeader& OP1aHeader() const;
 196
 197       /**
 198        * Warning: direct manipulation of MXF structures can interfere
 199        * with the normal operation of the wrapper.  Caveat emptor!
 200        *
 201        * @return RIP of the Track File
 202        *
 203        * @throws std::runtime_error if the Track File is not open
 204        */
 205       virtual const ASDCP::MXF::RIP& RIP() const;
 206
 207       /**
 208        * Creates and prepares an IAB Track File for reading.
 209        *
 210        * @param filename Path to the file. The file must no exist.
 211        *
 212        * @return RESULT_OK indicates that frames are ready to be read,
 213        * otherwise the reader is reset
 214        */
 215       Result_t OpenRead(const std::string& filename);
 216
 217       /**
 218        * Closes the IAB Track File.
 219        *
 220        * @return RESULT_OK indicates that the Track File was successfully closed.
 221        */
 222       Result_t Close();
 223
 224       /**
 225        * Fill a WriterInfo struct with the values from the Track File's header.
 226        *
 227        * @param  writer_info Struct to be filled
 228        * @return RESULT_OK indicates that writer_info was successfully filled.
 229        */
 230       Result_t FillWriterInfo(ASDCP::WriterInfo& writer_info) const;
 231
 232         /**
 233          * Reads an IA Frame.
 234          *
 235          * @param frame_number Index of the frame to be read. Must be in the range [0, GetFrameCount()).
 236          * @param frame Frame data. Must not be modified. Remains valid until the next call to ReadFrame().
 237          * @return RESULT_OK indicates that more frames are ready to be read,
 238          * otherwise the file is closed and the reader reset
 239          */
 240       Result_t ReadFrame(ui32_t frame_number, ASDCP::FrameBuffer& frame);
 241
 242       /** Reads a Generic Stream Partition payload. Returns RESULT_INIT if the file is
 243        * not open, or RESULT_FORMAT if the SID is not present in the  RIP, or if the
 244        * actual partition at ByteOffset does not have a matching BodySID value.
 245        * Encryption is not currently supported.
 246        */
 247       Result_t ReadGenericStreamPartitionPayload(ui32_t SID, ASDCP::FrameBuffer& FrameBuf);
 248
 249       /**
 250        * Returns the number of IA Frame in the Track File.
 251        *
 252        * @param frameCount Number of IA Frames
 253        * @return RESULT_OK unless the file is not open
 254        */
 255       Result_t GetFrameCount(ui32_t& frameCount) const;
 256
 257       // Print debugging information to stream
 258       void     DumpHeaderMetadata(FILE* = 0) const;
 259       void     DumpIndex(FILE* = 0) const;
 260     };
 261
 262   } //namespace IAB
 263
 264 } // namespace AS_02
 265
 266 #endif // AS_02_IAB_h__