AS_DCP_TimedText.h

   1 /*
   2 Copyright (c) 2003-2006, 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_Subtitle.h
  28     \version $Id$
  29     \brief   experimental AS-DCP subtitle
  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; // NULL-terminated string
  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 DCSubtitleParser
  99         {
 100           class h__SubtitleParser;
 101           mem_ptr<h__SubtitleParser> m_Parser;
 102           ASDCP_NO_COPY_CONSTRUCT(DCSubtitleParser);
 103
 104         public:
 105           DCSubtitleParser();
 106           virtual ~DCSubtitleParser();
 107
 108           // Opens the XML file for reading, parse data to provide a complete
 109           // set of stream metadata for the MXFWriter below.
 110           Result_t OpenRead(const char* filename) const;
 111
 112           // Fill a TimedTextDescriptor struct with the values from the file's contents.
 113           // Returns RESULT_INIT if the file is not open.
 114           Result_t FillDescriptor(TimedTextDescriptor&) const;
 115
 116           // Reads the complete Timed Text Resource into the given string.
 117           Result_t ReadTimedTextResource(std::string&) const;
 118
 119           // Reads the Ancillary Resource having the given ID. Fails if the buffer
 120           // is too small or the resource does not exist.
 121           Result_t ReadAncillaryResource(const byte_t* uuid, FrameBuffer&) const;
 122         };
 123
 124       //
 125       class MXFWriter
 126         {
 127           class h__Writer;
 128           mem_ptr<h__Writer> m_Writer;
 129           ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 130
 131         public:
 132           MXFWriter();
 133           virtual ~MXFWriter();
 134
 135           // Open the file for writing. The file must not exist. Returns error if
 136           // the operation cannot be completed or if nonsensical data is discovered
 137           // in the essence descriptor.
 138           Result_t OpenWrite(const char* filename, const WriterInfo&,
 139                              const TimedTextDescriptor&, ui32_t HeaderSize = 16384);
 140
 141           // Writes the Timed-Text Resource to the MXF file. The file must be UTF-8
 142           // encoded. If the optional AESEncContext argument is present, the essence
 143           // is encrypted prior to writing. Fails if the file is not open, is finalized,
 144           // or an operating system error occurs.
 145           // This method may only be called once, and it must be called before any
 146           // call to WriteAncillaryResource(). RESULT_STATE will be returned if these
 147           // conditions are not met.
 148           Result_t WriteTimedTextResource(const std::string& XMLDoc, AESEncContext* = 0, HMACContext* = 0);
 149
 150           // Writes an Ancillary Resource to the MXF file. If the optional AESEncContext
 151           // argument is present, the essence is encrypted prior to writing.
 152           // Fails if the file is not open, is finalized, or an operating system
 153           // error occurs. RESULT_STATE will be returned if the method is called before
 154           // WriteTimedTextResource()
 155           Result_t WriteAncillaryResource(const FrameBuffer&, AESEncContext* = 0, HMACContext* = 0);
 156
 157           // Closes the MXF file, writing the index and revised header.
 158           Result_t Finalize();
 159         };
 160
 161       //
 162       class MXFReader
 163         {
 164           class h__Reader;
 165           mem_ptr<h__Reader> m_Reader;
 166           ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 167
 168         public:
 169           MXFReader();
 170           virtual ~MXFReader();
 171
 172           // Open the file for reading. The file must exist. Returns error if the
 173           // operation cannot be completed.
 174           Result_t OpenRead(const char* filename) const;
 175
 176           // Returns RESULT_INIT if the file is not open.
 177           Result_t Close() const;
 178
 179           // Fill a TimedTextDescriptor struct with the values from the file's header.
 180           // Returns RESULT_INIT if the file is not open.
 181           Result_t FillDescriptor(TimedTextDescriptor&) const;
 182
 183           // Fill a WriterInfo struct with the values from the file's header.
 184           // Returns RESULT_INIT if the file is not open.
 185           Result_t FillWriterInfo(WriterInfo&) const;
 186
 187           // Reads the complete Timed Text Resource into the given string. Fails if the resource
 188           // is encrypted and AESDecContext is NULL (use the following method to retrieve the
 189           // raw ciphertet block).
 190           Result_t ReadTimedTextResource(std::string&, AESDecContext* = 0, HMACContext* = 0) const;
 191
 192           // Reads the complete Timed Text Resource from the MXF file. If the optional AESEncContext
 193           // argument is present, the resource is decrypted after reading. If the MXF
 194           // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 195           // will contain the ciphertext frame data. If the HMACContext argument is
 196           // not NULL, the HMAC will be calculated (if the file supports it).
 197           // Returns RESULT_INIT if the file is not open, failure if the frame number is
 198           // out of range, or if optional decrypt or HAMC operations fail.
 199           Result_t ReadTimedTextResource(FrameBuffer&, AESDecContext* = 0, HMACContext* = 0) const;
 200
 201           // Reads the timed-text resource having the given UUID from the MXF file. If the
 202           // optional AESEncContext argument is present, the resource is decrypted after
 203           // reading. If the MXF file is encrypted and the AESDecContext argument is NULL,
 204           // the frame buffer will contain the ciphertext frame data. If the HMACContext
 205           // argument is not NULL, the HMAC will be calculated (if the file supports it).
 206           // Returns RESULT_INIT if the file is not open, failure if the frame number is
 207           // out of range, or if optional decrypt or HAMC operations fail.
 208           Result_t ReadAncillaryResource(const byte_t* uuid, FrameBuffer&, AESDecContext* = 0, HMACContext* = 0) const;
 209
 210           // Print debugging information to stream
 211           void     DumpHeaderMetadata(FILE* = 0) const;
 212           void     DumpIndex(FILE* = 0) const;
 213         };
 214     } // namespace TimedText
 215
 216
 217
 218 } // namespace ASDCP
 219
 220
 221 #endif // _AS_DCP_SUBTITLE_H_
 222
 223
 224 //
 225 // end AS_DCP_Subtitle.h
 226 //