AS_DCP_TimedText.h

   1 /*
   2 Copyright (c) 2007, 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_DCP_TimedText.h
  28     \version $Id$
  29     \brief   experimental AS-DCP timed-text container
  30
  31     Implements Draft S429-5
  32 */
  33
  34 #include <AS_DCP.h>
  35 #include <list>
  36
  37
  38 #ifndef _AS_DCP_SUBTITLE_H_
  39 #define _AS_DCP_SUBTITLE_H_
  40
  41
  42 namespace ASDCP {
  43
  44   //
  45   namespace TimedText
  46     {
  47       enum MIMEType_t { MT_BIN, MT_PNG, MT_OPENTYPE };
  48
  49       struct TimedTextResourceDescriptor
  50       {
  51         byte_t      ResourceID[UUIDlen];
  52         MIMEType_t  Type;
  53
  54         TimedTextResourceDescriptor() : Type(MT_BIN) {}
  55       };
  56
  57       typedef std::list<TimedTextResourceDescriptor> ResourceList_t;
  58
  59       struct TimedTextDescriptor
  60       {
  61         Rational       EditRate;                //
  62         ui32_t         ContainerDuration;
  63         byte_t         AssetID[UUIDlen];
  64         std::string    NamespaceName;
  65         std::string    EncodingName;
  66         ResourceList_t ResourceList;
  67
  68       TimedTextDescriptor() : ContainerDuration(0), EncodingName("UTF-8") {} // D-Cinema format is always UTF-8
  69       };
  70
  71       // Print debugging information to stream (stderr default)
  72       void   DescriptorDump(const TimedTextDescriptor&, FILE* = 0);
  73
  74       //
  75       class FrameBuffer : public ASDCP::FrameBuffer
  76       {
  77         ASDCP_NO_COPY_CONSTRUCT(FrameBuffer); // TODO: should have copy construct
  78
  79       protected:
  80         byte_t      m_AssetID[UUIDlen];
  81         std::string m_MIMEType;
  82
  83       public:
  84         FrameBuffer() { memset(m_AssetID, 0, UUIDlen); }
  85         FrameBuffer(ui32_t size) { Capacity(size); memset(m_AssetID, 0, UUIDlen); }
  86         virtual ~FrameBuffer() {}
  87
  88         inline const byte_t* AssetID() const { return m_AssetID; }
  89         inline void          AssetID(const byte_t* buf) { memcpy(m_AssetID, buf, UUIDlen); }
  90         inline const char*   MIMEType() const { return m_MIMEType.c_str(); }
  91         inline void          MIMEType(const std::string& s) { m_MIMEType = s; }
  92
  93         // Print debugging information to stream (stderr default)
  94         void Dump(FILE* = 0, ui32_t dump_bytes = 0) const;
  95       };
  96
  97       //
  98       class IResourceResolver
  99       {
 100       public:
 101         virtual ~IResourceResolver() {}
 102         virtual Result_t ResolveRID(const byte_t* uuid, FrameBuffer&) const = 0; // return data for RID
 103       };
 104
 105       //
 106       class DCSubtitleParser
 107         {
 108           class h__SubtitleParser;
 109           mem_ptr<h__SubtitleParser> m_Parser;
 110           ASDCP_NO_COPY_CONSTRUCT(DCSubtitleParser);
 111
 112         public:
 113           DCSubtitleParser();
 114           virtual ~DCSubtitleParser();
 115
 116           // Opens the XML file for reading, parse data to provide a complete
 117           // set of stream metadata for the MXFWriter below.
 118           Result_t OpenRead(const char* filename) const;
 119
 120           // Fill a TimedTextDescriptor struct with the values from the file's contents.
 121           // Returns RESULT_INIT if the file is not open.
 122           Result_t FillDescriptor(TimedTextDescriptor&) const;
 123
 124           // Reads the complete Timed Text Resource into the given string.
 125           Result_t ReadTimedTextResource(std::string&) const;
 126
 127           // Reads the Ancillary Resource having the given ID. Fails if the buffer
 128           // is too small or the resource does not exist. The optional Resolver
 129           // argument can be provided which will be used to retrieve the resource
 130           // having a particulat UUID. If a Resolver is not supplied, the default
 131           // internal resolver will return the contents of the file having the UUID
 132           // as the filename. The filename must exist in the same directory as the
 133           // XML file opened with OpenRead().
 134           Result_t ReadAncillaryResource(const byte_t* uuid, FrameBuffer&,
 135                                          const IResourceResolver* Resolver = 0) const;
 136         };
 137
 138       //
 139       class MXFWriter
 140         {
 141           class h__Writer;
 142           mem_ptr<h__Writer> m_Writer;
 143           ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 144
 145         public:
 146           MXFWriter();
 147           virtual ~MXFWriter();
 148
 149           // Open the file for writing. The file must not exist. Returns error if
 150           // the operation cannot be completed or if nonsensical data is discovered
 151           // in the essence descriptor.
 152           Result_t OpenWrite(const char* filename, const WriterInfo&,
 153                              const TimedTextDescriptor&, ui32_t HeaderSize = 16384);
 154
 155           // Writes the Timed-Text Resource to the MXF file. The file must be UTF-8
 156           // encoded. If the optional AESEncContext argument is present, the essence
 157           // is encrypted prior to writing. Fails if the file is not open, is finalized,
 158           // or an operating system error occurs.
 159           // This method may only be called once, and it must be called before any
 160           // call to WriteAncillaryResource(). RESULT_STATE will be returned if these
 161           // conditions are not met.
 162           Result_t WriteTimedTextResource(const std::string& XMLDoc, AESEncContext* = 0, HMACContext* = 0);
 163
 164           // Writes an Ancillary Resource to the MXF file. If the optional AESEncContext
 165           // argument is present, the essence is encrypted prior to writing.
 166           // Fails if the file is not open, is finalized, or an operating system
 167           // error occurs. RESULT_STATE will be returned if the method is called before
 168           // WriteTimedTextResource()
 169           Result_t WriteAncillaryResource(const FrameBuffer&, AESEncContext* = 0, HMACContext* = 0);
 170
 171           // Closes the MXF file, writing the index and revised header.
 172           Result_t Finalize();
 173         };
 174
 175       //
 176       class MXFReader
 177         {
 178           class h__Reader;
 179           mem_ptr<h__Reader> m_Reader;
 180           ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 181
 182         public:
 183           MXFReader();
 184           virtual ~MXFReader();
 185
 186           // Open the file for reading. The file must exist. Returns error if the
 187           // operation cannot be completed.
 188           Result_t OpenRead(const char* filename) const;
 189
 190           // Returns RESULT_INIT if the file is not open.
 191           Result_t Close() const;
 192
 193           // Fill a TimedTextDescriptor struct with the values from the file's header.
 194           // Returns RESULT_INIT if the file is not open.
 195           Result_t FillDescriptor(TimedTextDescriptor&) const;
 196
 197           // Fill a WriterInfo struct with the values from the file's header.
 198           // Returns RESULT_INIT if the file is not open.
 199           Result_t FillWriterInfo(WriterInfo&) const;
 200
 201           // Reads the complete Timed Text Resource into the given string. Fails if the resource
 202           // is encrypted and AESDecContext is NULL (use the following method to retrieve the
 203           // raw ciphertet block).
 204           Result_t ReadTimedTextResource(std::string&, AESDecContext* = 0, HMACContext* = 0) const;
 205
 206           // Reads the complete Timed Text Resource from the MXF file. If the optional AESEncContext
 207           // argument is present, the resource is decrypted after reading. If the MXF
 208           // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 209           // will contain the ciphertext frame data. If the HMACContext argument is
 210           // not NULL, the HMAC will be calculated (if the file supports it).
 211           // Returns RESULT_INIT if the file is not open, failure if the frame number is
 212           // out of range, or if optional decrypt or HAMC operations fail.
 213           Result_t ReadTimedTextResource(FrameBuffer&, AESDecContext* = 0, HMACContext* = 0) const;
 214
 215           // Reads the timed-text resource having the given UUID from the MXF file. If the
 216           // optional AESEncContext argument is present, the resource is decrypted after
 217           // reading. If the MXF file is encrypted and the AESDecContext argument is NULL,
 218           // the frame buffer will contain the ciphertext frame data. If the HMACContext
 219           // argument is not NULL, the HMAC will be calculated (if the file supports it).
 220           // Returns RESULT_INIT if the file is not open, failure if the frame number is
 221           // out of range, or if optional decrypt or HAMC operations fail.
 222           Result_t ReadAncillaryResource(const byte_t* uuid, FrameBuffer&, AESDecContext* = 0, HMACContext* = 0) const;
 223
 224           // Print debugging information to stream
 225           void     DumpHeaderMetadata(FILE* = 0) const;
 226           void     DumpIndex(FILE* = 0) const;
 227         };
 228     } // namespace TimedText
 229
 230
 231
 232 } // namespace ASDCP
 233
 234
 235 #endif // _AS_DCP_SUBTITLE_H_
 236
 237
 238 //
 239 // end AS_DCP_Subtitle.h
 240 //