Copy asdcplib 2.5.11 into the tree.

1 files changed, 300 insertions, 26 deletions

diff --git a/asdcplib/README b/asdcplib/README
index 8a630647..5f2ece91 100755
--- a/asdcplib/README
+++ b/asdcplib/README
@@ -1,15 +1,26 @@
 
-$Id: README,v 1.75 2012/03/07 19:29:06 mikey Exp $
+$Id: README,v 1.97 2015/11/10 19:40:55 jhurst Exp $
 
 The asdcplib library is a set of objects that offer
 simplified access to files conforming to the sound and
 picture track file formats developed by the SMPTE Working
-Group DC28.20.
+Group DC28.20 (now TC 21DC).
 
-This work was originally funded by Digital Cinema
-Initiatives, LLC (DCI). Subsequent efforts have been funded
-by Deluxe Laboratories, Doremi Labs, CineCert LLC, Avica
-Technology and others.
+Recently, support has also been added for SMPTE draft ST
+2067-5 "IMF Essence Component", AKA "AS-02".  This code was
+donated by Fraunhofer IIS.  It carries additional copyright
+information which should be listed whenever you link the
+AS-02 elements of the library.  Please look at the top of
+the AS-02 files to see this copyright information.
+
+AS-02 support is carried in separate object modules, so
+unless you #include <AS_02.h> and link libas-02.so you are
+still using plain old asdcp.
+
+This work was originally funded by Digital Cinema Initiatives,
+LLC (DCI). Subsequent efforts have been funded by Deluxe
+Laboratories, Doremi Labs, CineCert LLC, Avica Technology
+and others.
 
 **The asdcplib project was originally housed on SourceForge.
 The project has moved to http://www.cinecert.com/asdcplib/
@@ -32,11 +43,11 @@ supporting this project.
 Design Notes
 
 This library is intended (but of course not limited) for
-use by developers of commercial D-Cinema products.  It is
-designed to be easily integrated into a wide variety of
-development environments.  Commercial users are strongly
-urged to use static linking (at least where you use this
-library) to prevent malicious in-field replacement of
+use by developers of commercial D-Cinema products (and now
+IMF!).  It is designed to be easily integrated into a wide
+variety of development environments.  Commercial users are
+strongly urged to use static linking (at least where you use
+this library) to prevent malicious in-field replacement of
 critical system modules. This recommendation should be
 considered wherever Open Source or Free software is being
 used in conjunction with critical security parameters, such
@@ -50,12 +61,15 @@ crypto functions can be replaced by linking to alternative
 implementations of the ASDCP:: objects which provide those
 services.
 
-AS_DCP.h contains the entire API.  You do not need to read
-any of the other files, except maybe asdcp-test.cpp which
-contains detailed usage examples of each of the API's
-services. The KM_* files may be of interest for general
-development support, but may be ignored if all you want
-is simple AS-DCP support.
+AS_DCP.h contains the entire AS-DCP API.  You do not need to
+read any of the other files, except maybe asdcp-test.cpp which
+contains detailed usage examples of each of the API's services.
+The KM_* files may be of interest for general development
+support, but may be ignored if all you want is simple AS-DCP
+support.
+
+Likewise, draft 2067-5 "IMF Essence Component" (AS-02) support
+is entirely contained in AS-02.h
 
 
 Build Instructions
@@ -67,9 +81,8 @@ MinGW installed. For those Windows users who would prefer to build
 this natively, an "nmake" build file and instructions can be found
 in the win32 subdirectory.  
 
-OpenSSL is also required, and the most recent version of v0.9.8 
-is recommended. See http://www.openssl.org/ for more information
-and download instructions.
+OpenSSL is also required, any recent version should be fine. See
+http://www.openssl.org/ for more information and download instructions.
 
 Optional support for writing Timed Text Track Files is supported by
 either Xerces-C or Expat. See http://xerces.apache.org/xerces-c/ or
@@ -77,7 +90,8 @@ http://expat.sourceforge.net/ for source and build instructions.
 
 To configure and build, type './configure' followed by 'make'. There
 are several test targets on the POSIX side, but you need to assemble
-a set of test files to use them.  
+a set of test files to use them.  AS-02 support can be enabled with 
+ --enable-as-02.  
 
 I have tested this build on win32, Linux, OpenBSD, and Darwin
 platforms. Others may work as well.
@@ -97,6 +111,10 @@ asdcp-info - Displays information about AS-DCP (MXF) track files.
 
 asdcp-util - Calculates digests and generates random numbers and UUIDs.
 
+as-02-wrap - Writes AS-02 Essence Component files.
+
+as-02-unwrap - Extracts essence from AS-02 Essence Component files.
+
 kmfilegen - Writes and verifies large files using a platform-
 independent format. Use it to test issues related to large files.
 
@@ -111,17 +129,272 @@ blackwave - Write a WAVE file full of zeros,  Used to make filler
 
 j2c-test - Displays information about JP2K codestreams.
 
+Experimental feature: Prototype for High Dynamic Range is a wrapper
+for the IMF application that allows JPEG-2000 codestreams to be paired
+with opaque blobs of metadata.  AS-02 support must be enabled to
+build this feature, so --enable-as-02 must be enabled if
+--enable-phdr is to be used.  The following executable programs will be
+built:
+
+phdr-wrap - Writes AS-02 PHDR Essence Component files.
+
+phdr-unwrap - Extracts essence from AS-02 PHDR Essence Component files.
+
 
 Documentation
 
-The API documentation is mostly in AS_DCP.h. Read that file for
-a detailed description of the library's capabilities. Read
-asdcp-test.cpp for library usage examples. The command-line
-utilities all respond to -h.
+The API documentation is mostly in AS_DCP.h. and AS_02.h  Read those
+files for a detailed description of the library's capabilities. Read
+asdcp-*.cpp and as-02-*.cpp files for library usage examples. The
+command-line utilities all respond to -h.
 
 
 Change History
 
+2015-11-10 - bug fixes, IMF text, pink noise
+ o I moved personal dev environment from older gcc to newer clang.  Many
+   small changes were made to satisfy the new compiler:
+   - Altered many printf format codes to use the correct format for the
+     given integer type.
+   - Parenthesized some expressions to clarify previously ambiguous
+     expectation about precedence.
+   - Created macro KM_MACOSX for use in OS-specific code selection.
+   - Removed last uses of the old C-language abs(), now using Kumu::xabs().
+   - Removed last uses of the old C-language atoi(), not using strtol().
+ o Added platform-independent call Kumu::GetExecutablePath() (to be tested
+   on win32).
+ o Added new capabilities to Result_t.
+ o Added imlementation of SMPTE ST 2092-1 pink noise generator.
+ o Added pinkwave CLI utility.
+ o Added font support to the IMF timed-text wrapper.
+ o Fixed a bug that was causing Array properties to be written without
+   the (count, length) header (from PAL).
+ o General review of Batch/Array distinction throughout the project.
+ o Cleaned up definitions of optional properties in all MXF metadata packs.
+ o Fixed Win32 build (from Crowe).
+ o Fixed a bug that caused incorrect failure when parsing JPEG 2000
+   codestreams having fewer than five decomposition levels. (from Korneder).
+ o Fixed missing UUID generation in some instances of the MCALinkID property.
+ o Added -w option to asdcp-wrap to support use of WTF label with MCA.
+ o Altered asdcp-wrap to recognize "-C <UL>" when MCA is being used.
+ o Fixed broken -A <w>/<h> option in as-02-wrap and phdr-wrap.
+ o asdcp-wrap and as-02-wrap now allow split channel groups in MCA labels.
+
+
+2015-02-23 - bug fixes
+  o Fixed a new bug introduced by the fix to large numbers of subtitle ancillary
+    resources.
+  o Added support for generic Aux Data (ST 429-14) to asdcp-wrap.
+
+
+2015-02-19 - PHDR feature, bug fixes
+  o Modified PCMParser and PCMParserList to return partial frame buffers at the
+    end of a WAV input file.  This was needed to allow wrapping all samples into
+    an AS-02 audio file (which is clip-wrapped) in the case where the input file
+    has an odd number of samples with respect to the frame buffer size being
+    used.  If there is more than one input file the length of the last buffer
+    will be determined by PCMParserList to be the shortest of the input files.
+    Prior to this change, partial samples in an input WAV file have been
+    abandoned (i.e., not written out to the MXF file).  As a result, AS-DCP
+    applications will have to decide whether to abandon the partial last frame
+    (usually detected by testing frame_buffer.Size() != frame_buffer.Capacity())
+    or write it to the MXF file.  Programs written to the old API will write the
+    partial frame (i.e., new behavior.)  This should not be harmful since the
+    remainder of the buffer is zeroed and the output file will contain one
+    additional edit unit compared to the previous version.
+  o asdcp-wrap has been modified to test for the partial buffer and by default
+    will complain and abandon the buffer (i.e., same behavior but with a warning
+    message.)  A new command line switch (-g) alters this behavior and writes
+    the buffer to the MXF file (it still warns the user that this condition is
+    present.)
+  o as-02-wrap now wraps all samples from the input file to the MXF file. There
+    is no padding, the clip is exactly the set of samples from the input.
+  o as-02 unwrap is temporarily restricted to creating wav files that are
+    aligned with the frame buffer size.  This means that the output file will
+    be longer than the original WAV input in the case where the input file has
+    an odd number of samples with respect to the frame buffer size being used.
+    The pad samples are zero (silence).
+  o Modified CalcFramesFromDurationInSamples() to increment the count by one for
+    the case where the input file has an odd number of samples with respect to
+    the frame buffer size being used (previously it truncated the odd samples.)
+  o Fixed ST 429-5 / ST 2067-5 wrapping to increase header space when ancillary
+    resources are present (fixes a bug that cause the header to overflow the
+    allotted space when large numbers of PNG files were present.)
+  o Refactored GetXMLDocType() to use the XML parser.
+  o Added ParseFirstFromString() method to Kumu::XMLElement
+  o Removed Kumu::StringIsXML from the API.
+  o Added ASDCP::MXF::RGBALayout type
+  o Added J2CLayout property to JPEG2000PictureSubDescriptor
+  o Changed km_token_split() to retain empty elements in the output list
+  o Added PHDR wrapping for AS-02.
+  o Added J2CLayout property to the JPEG2000PictureSubDescriptor.  This
+    support is preliminary: the Raw data type is being used instead of
+    RGBALayout type, which will be in the next release.
+
+
+2014-10-2 - Bug fixes and enhancements, 2.2.6
+  o Fixed erroneous 377-4 MCA identifier in AS_DCP_PCM dump routine
+  o Fixed erroneous byte 13 in
+    WaveAudioDescriptor_ReferenceAudioAlignmentLevel label
+  o Added missing implementation of -W option to as-02.unwrap
+  o Fixed erroneous use of d-cinema ChannelAssignment label in as-02-wrap
+
+
+2014-10-01 - Bug fixes and enhancements, 2.2.5
+  o Finished AS-02 text wrap/unwrap
+  o Fixed fractional seconds parsing for Timestamp objects
+  o Updated KLVPacket to use 64-bit length; allows huge packets
+    in AS-02 PCM files
+  o cleaned up use of atoi() in the library
+
+
+2014-07-09 - Additional IMF/AS-02 support, bug fixes and enhancements, 2.1.4
+  o Added IMF App 2 edit rates in AS_02 namespace: EditRate_29_97, 
+    EditRate_59_94. 
+  o Revised AEC CBC context objects to copy the key rather than  
+    keep the reference passed in to it.
+  o Addressed a bug that would allow unimpeded iteration of component 
+    values in a JP2K::PictureDescriptor object.
+  o Addressed a bug that was incorrectly recording the sequence Duration 
+    in MXF Track objects.
+  o Added ASDCP::AtmosSyncChannelMixer::AppendSilenceChannels()
+  o Added a QCD decoder to the j2c parser.
+  o Altered ASDCP::KLVPacket::HasUL() to use version-blind matching.
+  o Fixed an uninitialized variable in MemIOReader::ReadString() that  
+    caused unbounded reads.
+  o Fixed broken ByteString::ArchiveLength() method
+  o Fixed broken version numbers on SoundfieldGroupLinkID and  
+    GroupOfSoundfieldGroupsLinkID UL values.
+  o Added DBOXMotionCodePrimaryStream and DBOXMotionCodeSecondaryStream UL 
+    values to the internal dictionary.
+  o Added optional prefix handling to MCA label generator.
+  o Re-factored MCA label generator to include additional  
+    metadata (Thanks to Mike Radford).
+  o Added new options to as-02-wrap.
+
+
+2014-01-06 – Additional IMF/AS-02 support, bug fixes 2.1.1
+  o Fixed missing-index-partion bugs for AS-02 files.
+  o Moved LocalFilenameResolver into the AS_DCP public API so that it
+    can be used by other modules including AS-02.
+  o Did further refactoring of AS-02 Writer classes to separate CBR
+    and VBR indexing implementations.
+  o Fixed wave wrapping UL in clip-wrapped AS-02 files.  Renamed some
+    UL constants to reflect "clip" or "frame" wrapping.
+  o Re-factored JP2K_PDesc_to_MD() and MD_to_JP2K_PDesc() to work
+    with GenericPictureEssenceDescriptor objects.
+  o Fixed a bug that was suppressing PictureComponentSizing,
+    CodingStyleDefault and QuantizationDefault when writing the
+    essence descriptor in a JP2K file (AS-DCP and AS-02).
+  o Fixed the version byte on the following UL values:
+    	  StereoscopicPictureSubDescriptor
+	  GenericPictureEssenceDescriptor_ColorPrimaries
+	  GenericPictureEssenceDescriptor_ActiveHeight
+	  GenericPictureEssenceDescriptor_ActiveWidth
+	  GenericPictureEssenceDescriptor_ActiveXOffset
+	  GenericPictureEssenceDescriptor_ActiveYOffset
+  o Added some essence descriptor options to as-02-wrap.
+  o Changed bit rate display in asdcp-info from mebi-bits/s to
+    mega-bits/s.
+  o Added "SMPTE" / "Interop" format type display to asdcp-info.
+  o Improved integration of ST 377-4 MCA concepts with ST 429-2 static
+    labels.
+  o Modified asdcp-wrap to assume -L when wrapping timed-text (since
+    there is no MXF text wrapping for Interop.)
+  o Added new EssenceType_t values for IMF/AS-02 track files.
+  o Added detection for AS-02 track files to ASDCP::EssenceType()
+  o Changed lots of "const char*" to "const std::string&" in the
+    APIs defined by KM_fileio.h and AS_DCP.h.
+  o Fixed VBR Delta Segment entries to correctly flag progressive
+    material.
+  o Fixed PCM unwrapping bugs in as-02-unwrap.
+  o Fixed missing return statement in ArchivableString::ArchiveLength
+    (thanks to both Kristof Provost and Franck Chopin) 
+  o Fixed broken sample alignment in RF64Writer (thanks to Wolfgang
+    Woehl and Dolby)
+  o Fixed win32 build (thanks to Dolby)
+  o fixed a bug that caused blackwave to only produce 96kHz WAV files.
+    (thanks to Stephane W)
+
+
+2013-07-02 – IMF/AS-02 support, bug fixes 2.0.0
+  o Massive refactoring of internals to allow easier implementation
+    of AS-02.  Some API changes were made as well (note that
+    OPAtomHeader is now OP1aHeader and RIP is no longer part of the
+    OP1aHeader.)  If you are using this project as a library (and
+    especially if you are keeping patches against it) PLEASE TAKE
+    TIME TO EVALUATE THIS RELEASE THOUROUGHLY BEFORE ADDING IT TO
+    YOUR RELEASE PATH.
+  o Final integration of Fraunhoffer IIS code contribution.  AS-02
+    files are now fully supported with some TODOs and two major
+    exceptions: LEAD indexes are not supported by the MXF writers
+    and interlace images are not yet supported.
+  o Added support for MCA labels (ST 428-12) to asdcp-wrap.  Note
+    that this project is still in the early stages of interop testing
+    so errors are likely present and don't expect any server to
+    make use of this feature.
+
+
+2013-07-01 - Bug fixes, enhancements 1.12.50
+  o Fixed missing return statement in ArchivableString::ArchiveLength
+    (thanks to both Kristof Provost and Franck Chopin) 
+  o Fixed broken sample alignment in RF64Writer (thanks to Dolby)
+  o Fixed win32 build (thanks to Dolby)
+
+
+2013-04-12 - Dolby Atmos support and more audio labels 1.11.49
+  o Significant code contribution from Dolby Laboratories to add
+    support for generic data track files as proposed in ST 21DC
+    and also Dolby Atmos track file support as a specialization.
+  o Added Dolby-contributed code to support generating the external
+    sync signal for d-cinema as proposed in ST 21DC.
+  o Added Dolby-contributed code to support RF64 WAVE files.
+  o Fixed UL error in ST 429-5 DM encoding (contributed by Dolby).
+  o Added ULs for ST 428-12 and Amd. 429-2 2013.  Please check!
+
+
+2013-02-20 - bug fixes, enhancements 1.10.48
+ o Refactored internals of the AS-DCP file readers.  While no
+   changes in behavior are intended, users are cautioned to test
+   thouroughly before use in production.
+ o Fixed a bug in ReadAncillaryResource that was causing bogus HMAC
+   failures when reading resources from a file.
+ o Fixed premature-release bug in the Expat version of the XML parser.
+   Thanks to Carsten Feldheim (IIS) for the tip.
+ o Fixed -W option in asdcp-unwrap.  Thanks to RGB.
+ o Added P-HFR support to asdcp-wrap (see URL for details:
+   http://isdcf.com/papers/ISDCF-HighFrameRate-DCP.pdf).
+ o Added support for SMPTE ST 428-21 "Archival Frame Rates".
+ o Added -P option to asdcp-wrap (inserts arbitrary UL into the
+   PictureEssenceCoding property when wrapping JP2K files.)
+ o Added support for 96 kHz files to blackwave.
+ o Added new path and string manglers to Kumu.
+ o Updated MCA ULs (I warned you...).  Again please take some
+   time to proof this work against ST 477-4 including the latest
+   drafts of the registries.
+       Changed the version byte (8 0f 16) to 0x0e:
+           MCALabelSubDescriptor
+           AudioChannelLabelSubDescriptor
+           SoundfieldGroupLabelSubDescriptor
+           GroupOfSoundfieldGroupsLabelSubDescriptor
+	   GroupOfSoundfieldGroupsLinkID
+       Changed bytes 8 and and 13 of SoundfieldGroupLinkID
+       Added items to the UL dictionary:
+	   MCAPartitionKind
+	   MCAPartitionNumber
+	   MCATitle
+	   MCATitleVersion
+	   MCATitleSubVersion
+	   MCAEpisode
+	   MCAAudioContentKind
+	   MCAAudioElementKind
+
+
+2012-08-07 - bug fix, 1.10.46
+ o Added missing zero-initializers to time values when parsing a
+   timestamp string (in the case where the optional [Thh:mm.[:ss]]
+   syntax is not present in an encoded string).
+
 2012-03-06 - bug fixes, enhancements 1.9.45
  o Removed ASDCP::Timestamp, all items that were of that class are now 
    of class Kumu::Timestamp
@@ -240,7 +513,8 @@ Change History
  o ST 429-5 files have corrected ULs for DCTimedTextDescriptor and
    GenericStream DataElement. Files made with previous versions of
    the library are incompatible with this and future versions.
- o Fixed File Package TrackNumber values. Thanks to Sankar.
+ o Fixed File Package TrackNumber values. Th
+anks to Sankar.
  o Added edit rate constants to AS_DCP.h (25, 30, 50, 60).
  o Changed AudioDescriptor "SampleRate" element name to "EditRate"
    to make it consistent with the other types.