Added TimedText_Transform.h to the list of installable headers when using enable...
[asdcplib.git] / README
diff --git a/README b/README
index 18e237149812d209ee2cfef9e7c1338ea8050cf2..9897000cc836c5f20378c5a2ea6128bb8b40317f 100755 (executable)
--- a/README
+++ b/README
@@ -4,12 +4,23 @@ $Id$
 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.
 
@@ -114,14 +132,160 @@ j2c-test - Displays information about JP2K codestreams.
 
 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
 
+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 +404,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.