src/AS_02.h

   1 /*
   2 Copyright (c) 2011-2013, 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     class AS02IndexReader : public ASDCP::MXF::Partition
  73     {
  74       Kumu::ByteString m_IndexSegmentData;
  75       ui32_t m_Duration;
  76
  77       //      ui32_t              m_BytesPerEditUnit;
  78
  79       Result_t InitFromBuffer(const byte_t* p, ui32_t l);
  80
  81       ASDCP_NO_COPY_CONSTRUCT(AS02IndexReader);
  82       AS02IndexReader();
  83
  84     public:
  85       const ASDCP::Dictionary*&   m_Dict;
  86       Kumu::fpos_t  m_ECOffset;
  87       ASDCP::IPrimerLookup *m_Lookup;
  88
  89       AS02IndexReader(const ASDCP::Dictionary*&);
  90       virtual ~AS02IndexReader();
  91
  92       Result_t InitFromFile(const Kumu::FileReader& reader, const ASDCP::MXF::RIP& rip);
  93       ui32_t GetDuration() const;
  94       void     Dump(FILE* = 0);
  95       Result_t GetMDObjectByID(const Kumu::UUID&, ASDCP::MXF::InterchangeObject** = 0);
  96       Result_t GetMDObjectByType(const byte_t*, ASDCP::MXF::InterchangeObject** = 0);
  97       Result_t GetMDObjectsByType(const byte_t* ObjectID, std::list<ASDCP::MXF::InterchangeObject*>& ObjectList);
  98       Result_t Lookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry&) const;
  99     };
 100
 101   } // namespace MXF
 102
 103   //---------------------------------------------------------------------------------
 104   // Accessors in the MXFReader and MXFWriter classes below return these types to
 105   // provide direct access to MXF metadata structures declared in MXF.h and Metadata.h
 106
 107   // See ST 2067-5 Sec. x.y.z
 108   enum IndexStrategy_t
 109   {
 110     IS_LEAD,
 111     IS_FOLLOW,
 112     IS_FILE_SPECIFIC,
 113   };
 114
 115   namespace JP2K
 116   {
 117     //
 118     class MXFWriter
 119     {
 120       class h__Writer;
 121       ASDCP::mem_ptr<h__Writer> m_Writer;
 122       ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 123
 124     public:
 125       MXFWriter();
 126       virtual ~MXFWriter();
 127
 128       // Warning: direct manipulation of MXF structures can interfere
 129       // with the normal operation of the wrapper.  Caveat emptor!
 130       virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
 131       virtual ASDCP::MXF::RIP& RIP();
 132
 133       // Open the file for writing. The file must not exist. Returns error if
 134       // the operation cannot be completed or if nonsensical data is discovered
 135       // in the essence descriptor.
 136       Result_t OpenWrite(const char* filename, const ASDCP::WriterInfo&,
 137                          const ASDCP::JP2K::PictureDescriptor&,
 138                          const IndexStrategy_t& Strategy = IS_FOLLOW,
 139                          const ui32_t& PartitionSpace = 60, /* seconds per partition */
 140                          const ui32_t& HeaderSize = 16384);
 141
 142       // Writes a frame of essence to the MXF file. If the optional AESEncContext
 143       // argument is present, the essence is encrypted prior to writing.
 144       // Fails if the file is not open, is finalized, or an operating system
 145       // error occurs.
 146       Result_t WriteFrame(const ASDCP::JP2K::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
 147
 148       // Closes the MXF file, writing the index and revised header.
 149       Result_t Finalize();
 150     };
 151
 152     //
 153     class MXFReader
 154     {
 155       class h__Reader;
 156       ASDCP::mem_ptr<h__Reader> m_Reader;
 157       ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 158
 159     public:
 160       MXFReader();
 161       virtual ~MXFReader();
 162
 163       // Warning: direct manipulation of MXF structures can interfere
 164       // with the normal operation of the wrapper.  Caveat emptor!
 165       virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
 166       virtual AS_02::MXF::AS02IndexReader& AS02IndexReader();
 167       virtual ASDCP::MXF::RIP& RIP();
 168
 169       // Open the file for reading. The file must exist. Returns error if the
 170       // operation cannot be completed.
 171       Result_t OpenRead(const char* filename) const;
 172
 173       // Returns RESULT_INIT if the file is not open.
 174       Result_t Close() const;
 175
 176       // Fill an AudioDescriptor struct with the values from the file's header.
 177       // Returns RESULT_INIT if the file is not open.
 178       Result_t FillPictureDescriptor(ASDCP::JP2K::PictureDescriptor&) const;
 179
 180       // Fill a WriterInfo struct with the values from the file's header.
 181       // Returns RESULT_INIT if the file is not open.
 182       Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
 183
 184       // Reads a frame of essence from the MXF file. If the optional AESEncContext
 185       // argument is present, the essence is decrypted after reading. If the MXF
 186       // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 187       // will contain the ciphertext frame data. If the HMACContext argument is
 188       // not NULL, the HMAC will be calculated (if the file supports it).
 189       // Returns RESULT_INIT if the file is not open, failure if the frame number is
 190       // out of range, or if optional decrypt or HAMC operations fail.
 191       Result_t ReadFrame(ui32_t frame_number, ASDCP::JP2K::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
 192
 193       // Print debugging information to stream
 194       void     DumpHeaderMetadata(FILE* = 0) const;
 195       void     DumpIndex(FILE* = 0) const;
 196     };
 197
 198   } //namespace JP2K
 199
 200
 201   //---------------------------------------------------------------------------------
 202   //
 203   namespace PCM
 204   {
 205     // see AS_DCP.h for related data types
 206
 207     //
 208     class MXFWriter
 209     {
 210       class h__Writer;
 211       ASDCP::mem_ptr<h__Writer> m_Writer;
 212       ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 213
 214     public:
 215       MXFWriter();
 216       virtual ~MXFWriter();
 217
 218       // Warning: direct manipulation of MXF structures can interfere
 219       // with the normal operation of the wrapper.  Caveat emptor!
 220       virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
 221       virtual ASDCP::MXF::RIP& RIP();
 222
 223       // Open the file for writing. The file must not exist. Returns error if
 224       // the operation cannot be completed or if nonsensical data is discovered
 225       // in the essence descriptor.
 226       Result_t OpenWrite(const char* filename, const ASDCP::WriterInfo&,
 227                                 const ASDCP::PCM::AudioDescriptor&, ui32_t HeaderSize = 16384);
 228
 229       // Writes a frame of essence to the MXF file. If the optional AESEncContext
 230       // argument is present, the essence is encrypted prior to writing.
 231       // Fails if the file is not open, is finalized, or an operating system
 232       // error occurs.
 233       Result_t WriteFrame(const ASDCP::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
 234
 235       // Closes the MXF file, writing the index and revised header.
 236       Result_t Finalize();
 237     };
 238
 239     //
 240     class MXFReader
 241     {
 242       class h__Reader;
 243       ASDCP::mem_ptr<h__Reader> m_Reader;
 244       ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 245
 246     public:
 247       MXFReader();
 248       virtual ~MXFReader();
 249
 250       // Warning: direct manipulation of MXF structures can interfere
 251       // with the normal operation of the wrapper.  Caveat emptor!
 252       virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
 253       virtual AS_02::MXF::AS02IndexReader& AS02IndexReader();
 254       virtual ASDCP::MXF::RIP& RIP();
 255
 256       // Open the file for reading. The file must exist. Returns error if the
 257       // operation cannot be completed.
 258       Result_t OpenRead(const char* filename) const;
 259
 260       // Returns RESULT_INIT if the file is not open.
 261       Result_t Close() const;
 262
 263       // Fill an AudioDescriptor struct with the values from the file's header.
 264       // Returns RESULT_INIT if the file is not open.
 265       Result_t FillAudioDescriptor(ASDCP::PCM::AudioDescriptor&) const;
 266
 267       // Fill a WriterInfo struct with the values from the file's header.
 268       // Returns RESULT_INIT if the file is not open.
 269       Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
 270
 271       // Reads a frame of essence from the MXF file. If the optional AESEncContext
 272       // argument is present, the essence is decrypted after reading. If the MXF
 273       // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 274       // will contain the ciphertext frame data. If the HMACContext argument is
 275       // not NULL, the HMAC will be calculated (if the file supports it).
 276       // Returns RESULT_INIT if the file is not open, failure if the frame number is
 277       // out of range, or if optional decrypt or HAMC operations fail.
 278       Result_t ReadFrame(ui32_t frame_number, ASDCP::PCM::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
 279
 280       // Print debugging information to stream
 281       void     DumpHeaderMetadata(FILE* = 0) const;
 282       void     DumpIndex(FILE* = 0) const;
 283     };
 284   } // namespace PCM
 285
 286
 287
 288 } // namespace AS_02
 289
 290 #endif // _AS_02_H_
 291
 292 //
 293 // end AS_02.h
 294 //