2 Copyright (c) 2011-2013, Robert Scheler, Heiko Sparenberg Fraunhofer IIS, John Hurst
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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.
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.
29 \brief AS-02 library, public interface
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:
37 o SMPTE 2067-5:201X (draft at this time) IMF Essence Component
39 The following use cases are supported by the module:
41 o Write essence to a plaintext or ciphertext AS-02 file:
45 o Read essence from a plaintext or ciphertext AS-02 file:
49 o Read header metadata from an AS-02 file
61 // #include<Metadata.h> to use this
73 class OP1aIndexBodyPartion : public ASDCP::MXF::Partition
75 ASDCP::MXF::IndexTableSegment* m_CurrentSegment;
76 ASDCP::FrameBuffer m_Buffer;
77 ASDCP::MXF::Rational m_EditRate;
80 ASDCP_NO_COPY_CONSTRUCT(OP1aIndexBodyPartion);
83 const ASDCP::Dictionary*& m_Dict;
84 Kumu::fpos_t m_ECOffset;
85 ASDCP::IPrimerLookup* m_Lookup;
87 ui32_t m_BytesPerEditUnit;
88 ui32_t m_FramesWritten;
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);
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);
103 virtual ui64_t Duration();
104 virtual Result_t FillWriteToFile(Kumu::FileWriter& Writer, ui32_t numberOfIndexEntries);
107 virtual void PCMSetIndexParamsCBR(ui32_t sizeFirst, ui32_t sizeOthers);
108 virtual void PCMIndexLookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry& Entry) const;
113 class OP1aIndexFooter : public ASDCP::MXF::Partition
115 ASDCP::MXF::IndexTableSegment* m_CurrentSegment;
116 ASDCP::FrameBuffer m_Buffer;
117 ui32_t m_BytesPerEditUnit;
118 ASDCP::MXF::Rational m_EditRate;
120 ASDCP_NO_COPY_CONSTRUCT(OP1aIndexFooter);
124 const ASDCP::Dictionary*& m_Dict;
125 Kumu::fpos_t m_ECOffset;
126 ASDCP::IPrimerLookup* m_Lookup;
128 OP1aIndexFooter(const ASDCP::Dictionary*&);
129 virtual ~OP1aIndexFooter();
130 virtual Result_t InitFromFile(const Kumu::FileReader& Reader);
131 virtual Result_t InitFromPartitionBuffer(const byte_t* p, ui32_t l);
132 virtual Result_t InitFromBuffer(const byte_t* p, ui32_t l);
133 virtual Result_t WriteToFile(Kumu::FileWriter& Writer, ui64_t duration);
134 virtual void Dump(FILE* = 0);
136 virtual Result_t Lookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry&) const;
137 virtual void PushIndexEntry(const ASDCP::MXF::IndexTableSegment::IndexEntry&);
138 virtual void SetIndexParamsCBR(ASDCP::IPrimerLookup* lookup, ui32_t size, const ASDCP::MXF::Rational& Rate);
139 virtual void SetIndexParamsVBR(ASDCP::IPrimerLookup* lookup, const ASDCP::MXF::Rational& Rate, Kumu::fpos_t offset);
145 class AS02IndexReader
147 ASDCP::MXF::IndexTableSegment* m_CurrentSegment;
148 ASDCP::FrameBuffer m_Buffer;
149 ui32_t m_BytesPerEditUnit;
150 ASDCP::Rational m_EditRate;
153 ASDCP_NO_COPY_CONSTRUCT(AS02IndexReader);
157 const ASDCP::Dictionary*& m_Dict;
158 Kumu::fpos_t m_ECOffset;
159 ASDCP::IPrimerLookup *m_Lookup;
161 AS02IndexReader(const ASDCP::Dictionary*&);
162 virtual ~AS02IndexReader();
164 virtual Result_t InitFromFile(const Kumu::FileReader& Reader);
165 virtual void Dump(FILE* = 0);
167 virtual Result_t GetMDObjectByID(const Kumu::UUID&, ASDCP::MXF::InterchangeObject** = 0);
168 virtual Result_t GetMDObjectByType(const byte_t*, ASDCP::MXF::InterchangeObject** = 0);
169 virtual Result_t GetMDObjectsByType(const byte_t* ObjectID, std::list<ASDCP::MXF::InterchangeObject*>& ObjectList);
171 virtual Result_t Lookup(ui32_t frame_num, ASDCP::MXF::IndexTableSegment::IndexEntry&) const;
176 //---------------------------------------------------------------------------------
177 // Accessors in the MXFReader and MXFWriter classes below return these types to
178 // provide direct access to MXF metadata structures declared in MXF.h and Metadata.h
180 // See ST 2067-5 Sec. x.y.z
194 ASDCP::mem_ptr<h__Writer> m_Writer;
195 ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
199 virtual ~MXFWriter();
201 // Warning: direct manipulation of MXF structures can interfere
202 // with the normal operation of the wrapper. Caveat emptor!
203 virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
204 virtual ASDCP::MXF::RIP& RIP();
206 // Open the file for writing. The file must not exist. Returns error if
207 // the operation cannot be completed or if nonsensical data is discovered
208 // in the essence descriptor.
209 Result_t OpenWrite(const char* filename, const ASDCP::WriterInfo&,
210 const ASDCP::JP2K::PictureDescriptor&,
211 const IndexStrategy_t& Strategy = IS_FOLLOW,
212 const ui32_t& PartitionSpace = 60, /* seconds per partition */
213 const ui32_t& HeaderSize = 16384);
215 // Writes a frame of essence to the MXF file. If the optional AESEncContext
216 // argument is present, the essence is encrypted prior to writing.
217 // Fails if the file is not open, is finalized, or an operating system
219 Result_t WriteFrame(const ASDCP::JP2K::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
221 // Closes the MXF file, writing the index and revised header.
229 ASDCP::mem_ptr<h__Reader> m_Reader;
230 ASDCP_NO_COPY_CONSTRUCT(MXFReader);
234 virtual ~MXFReader();
236 // Warning: direct manipulation of MXF structures can interfere
237 // with the normal operation of the wrapper. Caveat emptor!
238 virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
239 virtual AS_02::MXF::AS02IndexReader& AS02IndexReader();
240 virtual ASDCP::MXF::RIP& RIP();
242 // Open the file for reading. The file must exist. Returns error if the
243 // operation cannot be completed.
244 Result_t OpenRead(const char* filename) const;
246 // Returns RESULT_INIT if the file is not open.
247 Result_t Close() const;
249 // Fill an AudioDescriptor struct with the values from the file's header.
250 // Returns RESULT_INIT if the file is not open.
251 Result_t FillPictureDescriptor(ASDCP::JP2K::PictureDescriptor&) const;
253 // Fill a WriterInfo struct with the values from the file's header.
254 // Returns RESULT_INIT if the file is not open.
255 Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
257 // Reads a frame of essence from the MXF file. If the optional AESEncContext
258 // argument is present, the essence is decrypted after reading. If the MXF
259 // file is encrypted and the AESDecContext argument is NULL, the frame buffer
260 // will contain the ciphertext frame data. If the HMACContext argument is
261 // not NULL, the HMAC will be calculated (if the file supports it).
262 // Returns RESULT_INIT if the file is not open, failure if the frame number is
263 // out of range, or if optional decrypt or HAMC operations fail.
264 Result_t ReadFrame(ui32_t frame_number, ASDCP::JP2K::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
266 // Print debugging information to stream
267 void DumpHeaderMetadata(FILE* = 0) const;
268 void DumpIndex(FILE* = 0) const;
274 //---------------------------------------------------------------------------------
278 // see AS_DCP.h for related data types
284 ASDCP::mem_ptr<h__Writer> m_Writer;
285 ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
289 virtual ~MXFWriter();
291 // Warning: direct manipulation of MXF structures can interfere
292 // with the normal operation of the wrapper. Caveat emptor!
293 virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
294 virtual ASDCP::MXF::RIP& RIP();
296 // Open the file for writing. The file must not exist. Returns error if
297 // the operation cannot be completed or if nonsensical data is discovered
298 // in the essence descriptor.
299 Result_t OpenWrite(const char* filename, const ASDCP::WriterInfo&,
300 const ASDCP::PCM::AudioDescriptor&, ui32_t HeaderSize = 16384);
302 // Writes a frame of essence to the MXF file. If the optional AESEncContext
303 // argument is present, the essence is encrypted prior to writing.
304 // Fails if the file is not open, is finalized, or an operating system
306 Result_t WriteFrame(const ASDCP::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
308 // Closes the MXF file, writing the index and revised header.
316 ASDCP::mem_ptr<h__Reader> m_Reader;
317 ASDCP_NO_COPY_CONSTRUCT(MXFReader);
321 virtual ~MXFReader();
323 // Warning: direct manipulation of MXF structures can interfere
324 // with the normal operation of the wrapper. Caveat emptor!
325 virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
326 virtual AS_02::MXF::AS02IndexReader& AS02IndexReader();
327 virtual ASDCP::MXF::RIP& RIP();
329 // Open the file for reading. The file must exist. Returns error if the
330 // operation cannot be completed.
331 Result_t OpenRead(const char* filename) const;
333 // Returns RESULT_INIT if the file is not open.
334 Result_t Close() const;
336 // Fill an AudioDescriptor struct with the values from the file's header.
337 // Returns RESULT_INIT if the file is not open.
338 Result_t FillAudioDescriptor(ASDCP::PCM::AudioDescriptor&) const;
340 // Fill a WriterInfo struct with the values from the file's header.
341 // Returns RESULT_INIT if the file is not open.
342 Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
344 // Reads a frame of essence from the MXF file. If the optional AESEncContext
345 // argument is present, the essence is decrypted after reading. If the MXF
346 // file is encrypted and the AESDecContext argument is NULL, the frame buffer
347 // will contain the ciphertext frame data. If the HMACContext argument is
348 // not NULL, the HMAC will be calculated (if the file supports it).
349 // Returns RESULT_INIT if the file is not open, failure if the frame number is
350 // out of range, or if optional decrypt or HAMC operations fail.
351 Result_t ReadFrame(ui32_t frame_number, ASDCP::PCM::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
353 // Print debugging information to stream
354 void DumpHeaderMetadata(FILE* = 0) const;
355 void DumpIndex(FILE* = 0) const;