src/AS_02.h

   1 /*
   2 Copyright (c) 2011-2012, Robert Scheler, Heiko Sparenberg Fraunhofer IIS, John Hurst
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions
   7 are met:
   8 1. Redistributions of source code must retain the above copyright
   9    notice, this list of conditions and the following disclaimer.
  10 2. Redistributions in binary form must reproduce the above copyright
  11    notice, this list of conditions and the following disclaimer in the
  12    documentation and/or other materials provided with the distribution.
  13 3. The name of the author may not be used to endorse or promote products
  14    derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27 /*! \file    AS_02.h
  28     \version $Id$
  29     \brief   AS-02 library, public interface
  30
  31 This module implements MXF AS-02 is a set of file access objects that
  32 offer simplified access to files conforming to the standards published
  33 by the SMPTE Media and Packaging Technology Committee 35PM. The file
  34 format, labeled IMF Essence Component (AKA "AS-02" for historical
  35 reasons), is described in the following document:
  36
  37  o SMPTE 2067-5:201X (draft at this time) IMF Essence Component
  38
  39 The following use cases are supported by the module:
  40
  41  o Write essence to a plaintext or ciphertext AS-02 file:
  42      JPEG 2000 codestreams
  43      PCM audio streams
  44
  45  o Read essence from a plaintext or ciphertext AS-02 file:
  46      JPEG 2000 codestreams
  47      PCM audio streams
  48
  49  o Read header metadata from an AS-02 file
  50 */
  51
  52 #ifndef _AS_02_H_
  53 #define _AS_02_H_
  54
  55 #include "AS_DCP.h"
  56 #include "MXF.h"
  57
  58
  59 namespace ASDCP {
  60   namespace MXF {
  61     // #include<Metadata.h> to use this
  62     class OPAtomHeader;
  63   };
  64 };
  65
  66 namespace AS_02
  67 {
  68   using Kumu::Result_t;
  69
  70   namespace MXF {
  71
  72     //
  73     class OP1aIndexBodyPartion : public ASDCP::MXF::Partition
  74     {
  75       ASDCP::MXF::IndexTableSegment*  m_CurrentSegment;
  76       ASDCP::FrameBuffer  m_Buffer;
  77       ASDCP::MXF::Rational m_EditRate;
  78       ui32_t                            klv_fill_size;
  79
  80       ASDCP_NO_COPY_CONSTRUCT(OP1aIndexBodyPartion);
  81
  82     public:
  83       const ASDCP::Dictionary*&  m_Dict;
  84       Kumu::fpos_t        m_ECOffset;
  85       ASDCP::IPrimerLookup*      m_Lookup;
  86
  87       ui32_t             m_BytesPerEditUnit;
  88       ui32_t             m_FramesWritten;
  89
  90       OP1aIndexBodyPartion(const ASDCP::Dictionary*&);
  91       virtual ~OP1aIndexBodyPartion();
  92       virtual Result_t InitFromFile(const Kumu::FileReader& Reader);
  93       virtual Result_t InitFromBuffer(const byte_t* p, ui32_t l);
  94       virtual Result_t WriteToFile(Kumu::FileWriter& Writer, ASDCP::UL& PartitionLabel);
  95       virtual void     Dump(FILE* = 0);
  96
  97       virtual bool Lookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry&,ui32_t&) const;
  98       virtual void PushIndexEntry(const ASDCP::MXF::IndexTableSegment::IndexEntry&);
  99       virtual void SetIndexParamsCBR(ASDCP::IPrimerLookup* lookup, ui32_t size, const ASDCP::MXF::Rational& Rate);
 100       virtual void SetIndexParamsVBR(ASDCP::IPrimerLookup* lookup, const ASDCP::MXF::Rational& Rate, Kumu::fpos_t offset);
 101
 102       //new
 103       virtual ui64_t Duration();
 104       virtual Result_t FillWriteToFile(Kumu::FileWriter& Writer, ui32_t numberOfIndexEntries);
 105
 106       //new for PCM
 107       virtual void PCMSetIndexParamsCBR(ui32_t sizeFirst, ui32_t sizeOthers);
 108       virtual void PCMIndexLookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry& Entry) const;
 109
 110     };
 111
 112     //
 113     class OP1aIndexFooter : public ASDCP::MXF::Partition
 114     {
 115       ASDCP::MXF::IndexTableSegment*  m_CurrentSegment;
 116       ASDCP::FrameBuffer  m_Buffer;
 117       ui32_t              m_BytesPerEditUnit;
 118       ASDCP::MXF::Rational m_EditRate;
 119       ui32_t              m_BodySID;
 120       ASDCP_NO_COPY_CONSTRUCT(OP1aIndexFooter);
 121
 122     public:
 123       const ASDCP::Dictionary*&   m_Dict;
 124       Kumu::fpos_t        m_ECOffset;
 125       ASDCP::IPrimerLookup*      m_Lookup;
 126
 127       OP1aIndexFooter(const ASDCP::Dictionary*&);
 128       virtual ~OP1aIndexFooter();
 129       virtual Result_t InitFromFile(const Kumu::FileReader& Reader);
 130       virtual Result_t InitFromPartitionBuffer(const byte_t* p, ui32_t l);
 131       virtual Result_t InitFromBuffer(const byte_t* p, ui32_t l);
 132       virtual Result_t WriteToFile(Kumu::FileWriter& Writer, ui64_t duration);
 133       virtual void     Dump(FILE* = 0);
 134
 135       virtual Result_t Lookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry&) const;
 136       virtual void     PushIndexEntry(const ASDCP::MXF::IndexTableSegment::IndexEntry&);
 137       virtual void     SetIndexParamsCBR(ASDCP::IPrimerLookup* lookup, ui32_t size, const ASDCP::MXF::Rational& Rate);
 138       virtual void     SetIndexParamsVBR(ASDCP::IPrimerLookup* lookup, const ASDCP::MXF::Rational& Rate, Kumu::fpos_t offset);
 139     };
 140
 141   } // namespace MXF
 142
 143
 144   //---------------------------------------------------------------------------------
 145   // Accessors in the MXFReader and MXFWriter classes below return these types to
 146   // provide direct access to MXF metadata structures declared in MXF.h and Metadata.h
 147
 148   // See ST 2067-5 Sec. x.y.z
 149   enum IndexStrategy_t
 150   {
 151     IS_LEAD,
 152     IS_FOLLOW,
 153     IS_FILE_SPECIFIC,
 154   };
 155
 156   namespace JP2K
 157   {
 158     //
 159     class MXFWriter
 160     {
 161       class h__Writer;
 162       ASDCP::mem_ptr<h__Writer> m_Writer;
 163       ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 164
 165     public:
 166       MXFWriter();
 167       virtual ~MXFWriter();
 168
 169       // Warning: direct manipulation of MXF structures can interfere
 170       // with the normal operation of the wrapper.  Caveat emptor!
 171       virtual ASDCP::MXF::OPAtomHeader& OPAtomHeader();
 172
 173       // Open the file for writing. The file must not exist. Returns error if
 174       // the operation cannot be completed or if nonsensical data is discovered
 175       // in the essence descriptor.
 176       Result_t OpenWrite(const char* filename, const ASDCP::WriterInfo&,
 177                          const ASDCP::JP2K::PictureDescriptor&,
 178                          const IndexStrategy_t& Strategy = IS_FOLLOW,
 179                          const ui32_t& PartitionSpace = 60, /* seconds per partition */
 180                          const ui32_t& HeaderSize = 16384);
 181
 182       // Writes a frame of essence to the MXF file. If the optional AESEncContext
 183       // argument is present, the essence is encrypted prior to writing.
 184       // Fails if the file is not open, is finalized, or an operating system
 185       // error occurs.
 186       Result_t WriteFrame(const ASDCP::JP2K::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
 187
 188       // Closes the MXF file, writing the index and revised header.
 189       Result_t Finalize();
 190     };
 191
 192     //
 193     class MXFReader
 194     {
 195       class h__Reader;
 196       ASDCP::mem_ptr<h__Reader> m_Reader;
 197       ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 198
 199     public:
 200       MXFReader();
 201       virtual ~MXFReader();
 202
 203       // Warning: direct manipulation of MXF structures can interfere
 204       // with the normal operation of the wrapper.  Caveat emptor!
 205       virtual ASDCP::MXF::OPAtomHeader& OPAtomHeader();
 206
 207       // Open the file for reading. The file must exist. Returns error if the
 208       // operation cannot be completed.
 209       Result_t OpenRead(const char* filename) const;
 210
 211       // Returns RESULT_INIT if the file is not open.
 212       Result_t Close() const;
 213
 214       // Fill an AudioDescriptor struct with the values from the file's header.
 215       // Returns RESULT_INIT if the file is not open.
 216       Result_t FillPictureDescriptor(ASDCP::JP2K::PictureDescriptor&) const;
 217
 218       // Fill a WriterInfo struct with the values from the file's header.
 219       // Returns RESULT_INIT if the file is not open.
 220       Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
 221
 222       // Reads a frame of essence from the MXF file. If the optional AESEncContext
 223       // argument is present, the essence is decrypted after reading. If the MXF
 224       // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 225       // will contain the ciphertext frame data. If the HMACContext argument is
 226       // not NULL, the HMAC will be calculated (if the file supports it).
 227       // Returns RESULT_INIT if the file is not open, failure if the frame number is
 228       // out of range, or if optional decrypt or HAMC operations fail.
 229       Result_t ReadFrame(ui32_t frame_number, ASDCP::JP2K::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
 230
 231       // Print debugging information to stream
 232       void     DumpHeaderMetadata(FILE* = 0) const;
 233       void     DumpIndex(FILE* = 0) const;
 234     };
 235
 236   } //namespace JP2K
 237
 238
 239   //---------------------------------------------------------------------------------
 240   //
 241   namespace PCM
 242   {
 243     // see AS_DCP.h for related data types
 244
 245     //
 246     class MXFWriter
 247     {
 248       class h__Writer;
 249       ASDCP::mem_ptr<h__Writer> m_Writer;
 250       ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 251
 252     public:
 253       MXFWriter();
 254       virtual ~MXFWriter();
 255
 256       // Warning: direct manipulation of MXF structures can interfere
 257       // with the normal operation of the wrapper.  Caveat emptor!
 258       virtual ASDCP::MXF::OPAtomHeader& OPAtomHeader();
 259
 260       // Open the file for writing. The file must not exist. Returns error if
 261       // the operation cannot be completed or if nonsensical data is discovered
 262       // in the essence descriptor.
 263       Result_t OpenWrite(const char* filename, const ASDCP::WriterInfo&,
 264                                 const ASDCP::PCM::AudioDescriptor&, ui32_t HeaderSize = 16384);
 265
 266       // Writes a frame of essence to the MXF file. If the optional AESEncContext
 267       // argument is present, the essence is encrypted prior to writing.
 268       // Fails if the file is not open, is finalized, or an operating system
 269       // error occurs.
 270       Result_t WriteFrame(const ASDCP::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
 271
 272       // Closes the MXF file, writing the index and revised header.
 273       Result_t Finalize();
 274     };
 275
 276     //
 277     class MXFReader
 278     {
 279       class h__Reader;
 280       ASDCP::mem_ptr<h__Reader> m_Reader;
 281       ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 282
 283     public:
 284       MXFReader();
 285       virtual ~MXFReader();
 286
 287       // Warning: direct manipulation of MXF structures can interfere
 288       // with the normal operation of the wrapper.  Caveat emptor!
 289       virtual ASDCP::MXF::OPAtomHeader& OPAtomHeader();
 290
 291       // Open the file for reading. The file must exist. Returns error if the
 292       // operation cannot be completed.
 293       Result_t OpenRead(const char* filename) const;
 294
 295       // Returns RESULT_INIT if the file is not open.
 296       Result_t Close() const;
 297
 298       // Fill an AudioDescriptor struct with the values from the file's header.
 299       // Returns RESULT_INIT if the file is not open.
 300       Result_t FillAudioDescriptor(ASDCP::PCM::AudioDescriptor&) const;
 301
 302       // Fill a WriterInfo struct with the values from the file's header.
 303       // Returns RESULT_INIT if the file is not open.
 304       Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
 305
 306       // Reads a frame of essence from the MXF file. If the optional AESEncContext
 307       // argument is present, the essence is decrypted after reading. If the MXF
 308       // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 309       // will contain the ciphertext frame data. If the HMACContext argument is
 310       // not NULL, the HMAC will be calculated (if the file supports it).
 311       // Returns RESULT_INIT if the file is not open, failure if the frame number is
 312       // out of range, or if optional decrypt or HAMC operations fail.
 313       Result_t ReadFrame(ui32_t frame_number, ASDCP::PCM::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
 314
 315       // Print debugging information to stream
 316       void     DumpHeaderMetadata(FILE* = 0) const;
 317       void     DumpIndex(FILE* = 0) const;
 318     };
 319   } // namespace PCM
 320
 321
 322
 323 } // namespace AS_02
 324
 325 #endif // _AS_02_H_
 326
 327 //
 328 // end AS_02.h
 329 //