X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=README;h=c44d43de304ac4fe312114b2ecc02a97b1025fee;hb=c457586e6fadd7c8b3547c59a7e30407842fce9b;hp=9646440b813d8cbac350537c488e8221c8a4cfab;hpb=c6900386fb66832781456838804ed7e28c535d63;p=asdcplib.git diff --git a/README b/README index 9646440..c44d43d 100755 --- a/README +++ b/README @@ -3,28 +3,26 @@ $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. +picture track file formats developed by the SMPTE Working +Group DC28.20. This work was originally funded by Digital Cinema -Initiatives, LLC. Subsequent efforts have been funded by -Deluxe Laboratories, Doremi Labs, and others. +Initiatives, LLC (DCI). Subsequent efforts have been funded +by Deluxe Laboratories, Doremi Labs, CineCert LLC, Avica +Technology 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 asdcplib project was originally housed on SourceForge. +The project has moved to http://www.cinecert.com/asdcplib/ -The project used to depend upon the mxflib project. Because -of the focus on covering the whole of the MXF spscifications, +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 interface that is now part of this library. -Special thanks to Matt Beard and Oliver Morgan for their great -work and support. +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 @@ -41,83 +39,336 @@ 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. +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 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. +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. 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 is +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. See http://www.openssl.org/ -OpenSSL is required if you want to read and write encrypted -AS-DCP files. See http://www.openssl.org +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. -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': +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. -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 +I have tested this build on win32, Linux, OpenBSD, and Darwin +platforms. Others may work as well. -I have tested this build on win32, Linux and Darwin platforms. -Others may work as well. -If you do not want to use or do not have OpenSSL, invoke -make with ASDCP_WITHOUT_OPENSSL defined: - - make ASDCP_WITHOUT_OPENSSL=1 -Build Versions +Utilities -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-test - Writes, reads and verifies AS-DCP (MXF) track files. -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: +kmfilegen - Writes and verifies large files using a platform- +independent format. Use it to test issues related to large files. - make SMPTE_LABELS=1 +kmuuidgen, kmrandgen - generate UUID values and random numbers. -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! +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). 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. +Currently, 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. Change History + +2009.03.08 - SMPTE format fixes, enhancements and bug fixes, v.1.4.21 + o Added build option (CONFIG_RANDOM_UUID) to enable mixed case UUID + generation when environment variable KM_USE_RANDOM_UUID is defined. + o Fixed a condition that could cause an error to occur whenwrapping + SMPTE format timed text track files that do not define a starting + frame. + o Updated ULs for SMPTE format track files. + o SampleRate added to JP2K metadata + o Support for wrapping 96kHz WAV files added. + o Updated ULs for audio channel formats (ChannelFormat) + o Updated font subdescriptor MIME Types for TimedText Trackfiles. + o Changed time implementation to support dates beyond Jan 19th, 2038. + o Xerces-C XML parser support added. + o New build method for Windows (see win32/README.txt for details). + + +2008.02.16 - SMPTE format fixes, bug fixes v.1.3.18 + o Added correct SMPTE UL for StereoscopicPictureSubDescriptor. + o Exposed JP2K metadata parser as ParseMetadataIntoDesc(). + o Added simple stereoscopic framebuffer to support paired ReadFrame() + and WriteFrame() methods (allows simpler integration with other + single-buffer code). + o Improved detection of JPEG Interop stereoscopic files. + o Win32 build fixes (Thanks to Mike Crowe at DTS). + o Added the WITH_MD macro to the makefile. Set this value to one + to build Win32 with /MD[d] instead of /MT[d]. + o The Generic Container UL has been added to the EssenceContainers + set in the header partition pack for encrypted files. It has always + been there in plaintext files. + - Below this point the changes are internal and should not affect you + unless you use Kumu directly. + o Major refactoring of KM_log.[h|cpp]. + o Fixed buffer re-sizing issue in Kumu::ByteString. + o Replaced type IdentifierList with ArchivableList. + o Added COPYING file to the release bundle. + + +2007.12.13 - Bug fixes v.1.2.17 + o Changed Result_t implementation to use int instead of long, which + was causing trouble on some 64 bit platforms. + o Fixed EKLV HMAC. NOTE: Breaks backward compatibility with older + Interop files. To validate these files, use asdcplib-1.1.14. This + should not cause too much trouble since files with broken and + non-broken HMAC have been in the wild for years without issue. + o Fixed HMAC sequence numbering in encrypted stereoscopic files. + o Finished stereoscopic test targets in the makefile. + o Fixed the win32 build, now expects VS2005 compiler by default, + use WITH_VC6=1 top get VC6 flags. + o Stereoscopic and Timed Text modes now have SMPTE UL values. + NOTE: SMPTE 429-5 and 429-10 are not yet published. It is possible + that these UL values may change before publication. Please use + caution when using these features for production work. + o Changed a bunch of symbol names in the 429-5 implementation to + better match the spec. + o Added -U option to asdcp-test to dump the UL library to stdout. + o Fixed erroneous placement of the PictureEssenceCoding UL in JP2K + files (Interop and SMPTE modes). + + +2007.10.22 - Timed Text, Stereoscopic Picture and Bug fixes v.1.2.16 + o Significant API changes have been made. Please read all entries + in this changelog to be sure you understand the changes. Also + note that some changes have been made to LS_MXF_SMPTE files that + are incompatible with earlier releases (e.g., EKLV HMAC). If + you are looking for a stable interop release, use v.1.1.14. + o Fixed RFC 2104 HMAC implementation for LS_MXF_SMPTE only. The + broken implementation has been maintained for Interop mode. + o Added support for draft SMPTE 429-5 Timed Text Track File. This + is still waiting for official SMPTE ULs, so do not use it for + shipping products. An XML parser is needed to create a Timed + Text Track File; Expat is now an optional part of the build. + Make with WITH_XML_PARSER=1 to link with Expat. If you do not + link with expat, you will get an error when using the TimedText:: + DCSubtitleParser class. See also S429-5-cgi.cpp for an example + that shows how to serve plaintext MXF file elements directly via + HTTP. + o Added support for draft SMPTE 429-10 Stereoscopic Picture Track + File, including the JPEG Interop version. This is still waiting + for official SMPTE ULs, so do not use it with LS_MXF_SMPTE for + shipping products. + o Refactored the following files as a side-effect of the above + work: AS_DCP_JP2K.cpp AS_DCP_MPEG2.cpp AS_DCP_PCM.cpp + AS_DCP_MXF.cpp AS_DCP_internal.h MXF.[h|cpp] MXFTypes.[h|cpp] + Metadata.[h|cpp] h__Reader.cpp h__Writer.cpp klvwalk.cpp. + WARNING: While significant effort has been extended to make sure + that these changes do not affect existing stable file support, + users are cautioned to test this release thouroughly. + o Added a large set of filesystem path manglers to KM_fileio.h. See + path-test.cpp for example usage. The path manglers have not yet + been tested on win32 platforms (they are currently used only by + the Timed Text module. + o The PathIsFile(), PathIsDirectory() and FileSize() subroutines + have been modified to accept const std::string& instead of + const char*. + o Added namespace and parsing support (Expat) to Kumu::XMLElement + (currently used only for Timed Text support). Also added some + new accessors. + o Altered MXF::UTF16String to use mbtowc() and wctomb(). + + +2007.03.31 - Bug fixes v.1.1.14 + o Fixed KeyFrameOffset value in MPEG wrapping to have negative + value. This is probably not yet complete for handling all + types of GOPs. Please send chunks of MPEG-2 VES that you + find which break this. Thanks to Doremi. + ** no other file format changes in this release ** + o Fixed error in RIP interpretation when reading arbitrary (i.e., + non-MXF) files. + o Fixed a memory leak in ASDCP::MXF::OPAtomHeader when used + in read mode. Thanks to Mahesh Bajaj for pointing out this + bug and the one above. + o Removed asserts from KM_fileio, replaced with RESULT_WRITEFAIL + return value statements. + o Added -s and -p to the makefile install target. + o Altered ByteString behavior to use target Length() in copy + operations (instead of Capacity()). + o Added new Set() method to ByteString. + o Fixed a bug in ByteString::Unarchive() that caused the operation + to fail when the buffer was smaller than the read (i.e., when + Capacity() was called). + o Added IdentifierList class to KM_util.h. + o Changed some Error() messages to Debug() in Wav.cpp + o Revived jp2k-test.cpp and asdcp-mem-test.cpp (they both had + stale #includes). + + +2007.02.15 - Bug fixes v1.1.13 + o Removed 'VDescObj->SampleRate.Numerator = VDesc.FrameRate;' + from MPEG2_VDesc_to_MD() in AS_DCP_MPEG2.cpp, was line 76. + o Added KM_TEST_NULL_STR_L() and KM_TEST_NULL_L() macros to + KM_log.h. These versions log the location of the null value. + Macros are now used in any module that includes KM_log.h. + o MPEG2 VES with run of zero values at the head is now OK. + o Increased VESHeaderBufSize to 16K. + o Added makefile support for local OpenSSL in ../openssl, if + present. + o The Kumu::PathIs*() functions now return false if a null or + empty string is given (used to be an assert). + o Cleaned up the install target in the makefile. + o Fixed SMPTE 429-6 HMAC -- FIPS 186-2 implementation was + laughably incorrect. Thanks to Doremi for pointing this out. + o Removed default parameter to HMACContext::InitKey(). + o Cleaned up messages and CLI arg handling in asdcp-test. + + +2006.11.19 - Mo better stuff v1.1.12 + o Changed read-only Result_t accessor methods to const. + o Added Base64 (-B) option to kmrandgen. + o Removed 16-bit alignment restriction from kmrandgen. + o Improved WAV file extraction speed (Thanks to Jim Radford + for pointing this out). + o Added single-channel split for WAV extraction (asdcp-test -1). + o Fixed remainder bug in h__RNG::fill_rand(). + + +2006.11.03 - Bug fixes v1.1.11 + o Increased index table entry list size to 5000. + o Added length checking to TLV writer (returns error if TLV + payload exceeds 64kB). + o Fixed partition header and RIP errors related to 2-partition + files (MXF Interop mode). + o Added -t option to asdcp-test (SHA-1 digest with Base64 output + on stdout). + o Fixed Sub Descriptor reference bug (Thanks to Denis Leconte + for dogged determination). + o Added directory-of-wav detection to RawEssenceType() + o Modified MXF::Partition::AddChildObject() to only generate + a UUID if the InstanceID is unset. + o Added ComponentMaxRef & ComponentMinRef to RGBAEssenceDescriptor. + More to follow. + o Added detection of 2K/4K jp2c, writing correct 4K metadata. + + +2006.10.05 - Bug fixes v1.1.10 + o Changed RM_RELEASE to RL_RELEASE in MXFTypes.h. + o Changed the MXF writer to use RL_RELEASE (was RL_DEVELOPMENT). + o Really fixed source reference chain. + o Updated JP2K file package label. + o Changed location of JPEG2000PictureSubDescriptor in the + header (was erroneously before Preface). + o Altered LS_MXF_INTEROP to produce 2-partition files. + + +2006.09.25 - Bug fixes v1.1.9 + o Fixed SourcePackageID value. All files will be 'original', + i.e. SourcePackageID will be all zeros. Let me know if you + want to set SourcePackageID. + o Fixed compiler warnings on some Linux platforms + o Fixed the build so that BUILD_DIR is no longer created + as a dependency. + o Added duration detection to the raw essence parsers. The + MPEG parser uses a nasty approximation so don't use it + without paying close attention to the result. + o Modified PCMParserList to make it more useful as a base + class. + o Fixed bugs and re-organized command-line help in asdcp-test + and klvwalk. + o Fixed two-partition file reads. + o Fixed Win32 PRNG initialization. + o Renamed asdcp-lf-test as kmfilegen. + o Added kmrandgen and kmuuidgen. + o Added string retrieval mechanism to Result_t. + o Refactored Kumu::Identifier and its sub-classes. + o Altered Kumu::PathIsFile to return true when the path + is a symbolic link (unix only). + o Altered Kumu::FileWriter::OpenWrite to use file creation + mode 0664 (was 0644) (unix only). + o Added Kumu::WriteStringIntoFile() subroutine. + + +2006.04.05 - Bug fixes and new stuff v1.1.7 + o Fixed a bug in the MPEG parser that caused it to fail when + handling start codes spanning buffer boundaries + o Added wavesplit and blackwave utility programs + o Added support for revised SMPTE HMAC key derivation when + using LS_MXF_SMPTE + o Refactored platform compatibility and general utilities + into a new sub-library "Kumu". There are no new build + steps or dependencies, but some important things have + changed: + + Result_t is no longer an enum, it is now a class. + Library result codes are now declared as const objects + like this: + + const Kumu::Result_t RESULT_FORMAT (-101, "The file..."); + + The macros ASDCP_SUCCESS and ASDCP_FAILURE still work + the same way thanks to an operator overload for type long. + See KM_error.h for more information. + + The logging interface has been moved out of AS_DCP.h + and into KM_log.h + o Some of the command line utilities that were using headers + other than AS_DCP.h have been changed to use the Kumu + equivalents. If you have code based on those utilities, you + will have to update by hand. + o Added new types to the EssenceType_t enum. + o The guard macro for Win32 code has changed from WIN32 to + KM_WIN32. + + +2006.03.2x - new stuff + o Proper handling of stream-id byte of essence UL values + o writes 3-partition files, reads 2-part or 3-part + + +2006.03.16 - bug fixes plus + o Removed SMPTE_LABELS compile-time option. The reader will now + silently accept either SMPTE or MXF Interop labels, the writer + can be instructed which to use at runtime. Default is Interop. + o Added an AIFF reader. Support is preliminary, it works with the + AIFF files I have on hand. + o More code refactoring. More to come. + + +2006.03.09 - full read-write + o Removed ASDCP_WITHOUT_OPENSSL compile-time option. + o Full read/write now working on new MXF library + + 2005.00.00 - A New Hope o The temporary mxf-lite has been removed. MXF files are now managed via the objects in KLV.h, MXFTypes.h MXF.h and