X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=README;h=2ba249e18de0f4a2e95d6cede21dc7d4c5f86ab6;hb=665b2e2e5dcf2266e636d29bcf4ef281da65117f;hp=3faf3dc12c1390b2515e78e765c471b584c4b04a;hpb=9bfe9676115531eb76649e1ebd5e14b904b53ae2;p=asdcplib.git diff --git a/README b/README index 3faf3dc..2ba249e 100755 --- a/README +++ b/README @@ -3,28 +3,37 @@ $Id$ The asdcplib library is a set of objects that offer simplified access to files conforming to the sound and -picture track file formats proposed by the SMPTE working -group DC-28.20. - -This work was originally funded by Digital Cinema -Initiatives, LLC. Subsequent efforts have been funded by -Deluxe Laboratories, Doremi Labs, and others. - -**The asdcplib project is housed on SourceForge. The project -home page is at http://sourceforge.net/projects/asdcplib. -There is not much there other than CVS because I don't -really have the time to master SourceForge administration. -Feel free to email with questions or to request a tar file. - -The project used to depend upon the mxflib project. Because -of the focus on covering the whole of the MXF spscifications, +picture track file formats developed by the SMPTE Working +Group DC28.20 (now TC 21DC). + +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 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/ + +The project formerly depended upon the mxflib project. Because +of its focus on covering the whole of the MXF specifications, mxflib is considerably larger and more complex that what I require for this application. For this reason I have created a dedicated MXF implementation that is now part of this library. Special thanks to Matt Beard and Oliver Morgan for their great work and support. -Thanks also to the members of the SMPTE DC-28.20 packaging +Thanks also to the members of the SMPTE DC28.20 packaging ad-hoc group and the members of the MXF Interop Initiative for their encouragement and support. Special thanks to Jim Whittlesey and Howard Lukk at DCI for proposing and @@ -34,88 +43,723 @@ 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 for applications having non-trivial security -requirements. - -The author strives mightily to provide an API that is -completely independent of operating system and other -library dependencies, and which allows selective replacement -of some modules for local needs. Specifically, the essence -parsers and OpenSSL 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 +used in conjunction with critical security parameters, such +as cryptographic keys. + +The author strives mightily to provide an API that is completely +independent of operating system and other library dependencies, +and which allows selective replacement of some modules for +local needs. Specifically, the essence parsers and OpenSSL +crypto functions can be replaced by linking to alternative +implementations of the ASDCP:: objects which provide those services. +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 -GNU make is required to build asdcplib. The makefile will -work on win32 systems that have Cygwin. Other win32 gmake -packages may or may not work depending upon the availability -of standard POSIX shell commands. You will need gcc to rebuild -the dep.make file. +On more-or-less POSIX systems (OS X, Linux, and BSD), GNU make and +autotools are required to build asdcplib. The same configure script +will also build this package on Windows machines with Cygwin and +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, 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 +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. 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. + + -OpenSSL is also required. See http://www.openssl.org -If you are building on win32 or a unix with no OpenSSL library -support, you will have to also obtain and build OpenSSL (I'm -using 0.9.7d on win32). Unpack it into the same parent directory -as asdcplib/, and rename the directory as (or make a sym link -named) 'openssl': +Utilities -myhost$ ls -l -total 1761 -drwxr-xr-x 1 jhurst None 0 Feb 3 16:37 asdcplib -drwxr-xr-x 56 jhurst None 0 Feb 2 16:35 openssl +asdcp-test - Writes, reads and verifies AS-DCP (MXF) track files. -I have tested this build on win32, Linux and Darwin platforms. -Others may work as well. +asdcp-wrap - Writes AS-DCP (MXF) track files. +asdcp-unwrap - Extracts essence from AS-DCP (MXF) track files. -Build Versions +asdcp-info - Displays information about AS-DCP (MXF) track files. -There are two flavors of build: the default build and the -"SMPTE_LABELS" build. Unless you are specifically working on -emerging SMPTE standards for D-Cinema content, you will certainly -want the default build. If you are developing support for the MXF -Interop Initiative standards, the default build is for you! +asdcp-util - Calculates digests and generates random numbers and UUIDs. -If you are not aiming for MXF Interop and if you are working -on developing support for the very latest versions of the SMPTE -draft standards, then you want the SMPTE_LABELS build: +as-02-wrap - Writes AS-02 Essence Component files. - make SMPTE_LABELS=1 +as-02-unwrap - Extracts essence from AS-02 Essence Component files. -NOTE: If you choose the SMPTE_LABELS build, you will be creating -files that may not work on MXF Interop systems. In the case of -encryption, incompatibility with MXF Interop is guaranteed! You -have been warned! +kmfilegen - Writes and verifies large files using a platform- +independent format. Use it to test issues related to large files. + +kmuuidgen, kmrandgen - generate UUID values and random numbers. + +wavesplit - Splits a WAVE file into two or more output files. Used + to untangle incorrectly-paired DCDM sound files. + +blackwave - Write a WAVE file full of zeros, Used to make filler + tracks (though you would be better off modifying asdcp-test if + this is a common use case). + +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 -Currently, the 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. More detailed documentation will be written RSN. +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-01-22 - PHDR feature, bug fixes + 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 + o Refactored Kumu::Timestamp to use KM_tai for internal representation + (replaced public Y M D, h, m, s variables) + o Refactored Kumu::Timestamp to use KM_tai for WIN32 builds + o Added UTC offset awareness to Kumu::Timestamp + o Replaced "long GetSecondsSinceEpoch(void) const" with + "ui64_t GetCTime() const" + o Corrected UL version segment in "7.1 DS" and "WTF" audio format + labels (corresponds with publication of ST 429-2:2011). + o Exposed MXF object interface (MXF.h, Metadata.h) via ASDCP MXFReader + and MXFWriter classes. + o Added UL values from ST 377-4:2012. >>>>NOTE: These are preliminary + values, subject to change upon final publication of not only ST 377-4 + but also the relevant registries. This is a good time to compare them + to the standard and complain if you think they are wrong! + o Added MCALabelSubDescriptor, AudioChannelLabelSubDescriptor, + SoundfieldGroupLabelSubDescriptor, and + GroupOfSoundfieldGroupsLabelSubDescriptor (from ST 377-4:2012) to + Metadata.h + o Changed some internals to make MXFWriter::OPAtomHeader() work correctly. + o Split asdcp-test into several different programs to help relieve + the impenetrable-list-of-arguments problem. asdcp-wrap, asdcp-unwrap + and asdcp-info take the place of asdcp-test's -c, -x and -i options, + respectively. asdcp-util contains the remaining functions. Note that + asdcp-test is now DEPRECATED, new functionality and bug fixes will be + aimed at the new tools. Also note that some options and calling + conventions are different for the new tools as compared to asdcp-test. + Please read the synopses and make sure you understand the new idioms. + o asdcp-wrap has a new argument, -C