X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=README;h=6c04d2db0bac3bce9e0c774f84d8a9eff62e71e2;hb=6e07e413f784e870a78b77767f9546eaf8d20935;hp=acad68fea28b81fb9f0a33eb329f75e269271a60;hpb=fe443bd90d915478994953b56836577a96ea4a28;p=asdcplib.git diff --git a/README b/README index acad68f..6c04d2d 100755 --- a/README +++ b/README @@ -4,15 +4,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 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. -**The asdcplib project was housed on SourceForge. The project -has moved to http://www.cinecert.com/asdcplib/ +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, @@ -32,56 +43,57 @@ 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. +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. +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. 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 -GNU make is required to build asdcplib. The makefile will work -on win32 systems that have Cygwin and MSVC. 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. +Build Instructions -OpenSSL is also required. See http://www.openssl.org/ +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. -If you are building on win32 or a unix with no OpenSSL library -support, you will have to also obtain and build OpenSSL. Unpack -it into the same parent directory as asdcplib/, and rename (or make -a symlink to) the directory as 'openssl': +OpenSSL is also required, any recent version should be fine. See +http://www.openssl.org/ for more information and download instructions. -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 +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 build, type 'make'. There are several test targets but you -need to assemble a set of test files to use them. +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 +I have tested this build on win32, Linux, OpenBSD, and Darwin platforms. Others may work as well. @@ -89,7 +101,19 @@ platforms. Others may work as well. Utilities -asdcp-test - Writes, reads and verifies AS-DCP (MXF) track files. +asdcp-test - Writes, reads and verifies AS-DCP (MXF) track files. + +asdcp-wrap - Writes AS-DCP (MXF) track files. + +asdcp-unwrap - Extracts essence from AS-DCP (MXF) track files. + +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. @@ -99,49 +123,741 @@ 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). +blackwave - Write a WAVE file of zeros. + +pinkwave - Write a WAVE file of SMPTE ST 2095 pink noise. + +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 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 -2007.06.xx - Timed Text and Bug fixes v.1.1.15 - o Added support for draft SMPTE 429-5 Timed Text Track File. See - AS_DCP_TimedText.h for the API. This is *very* experimental, so - do not use for shipping products. Timed Text support is NOT part - of the default build, run `make WITH_TIMED_TEXT=1` to enable - this part of the library. AS_DCP_TimedText.h will be combined - with AS_DCP.h when it becomes stable. Because we need an XML - parser to create the Track File, expat is now part of the Timed - Text build. Follow the XML_PARSER macro in the makefile and KM_xml - to see how you can support your favorite parser. See also - S429-5-cgi.cpp for an example that shows how to serve plaintext - MXF file elements directly via HTTP. + +2018-10-15 - 2.10.31 + o NOTE: Use of MXFGCGenericEssenceMultipleMappings in AS-02 files is not + defined by standards and will soon be withdrawn from this library. If you + would like to experience this change now, define the macro + ASDCP_GCMULTI_PATCH + o Removed PIMD support (unused prototype) + o Returned the DataEssenceCoding UL version byte to "5" in Atmos files + o Fixed ColorPrimaries_ACES UL version byte + o Added "FSKSync" audio channel label to the MCA label generator + o SMPTE RDD 45 requires a minimum BER encoding length of five (5) bytes for + Content Element packets. The Write_EKLV_Packet() API has been modified to + allow the specification of this value. All existing wrapping modules have + been changed to conform to the new API, and all continue to use four (4) + as the minimum BER encoding length. Write_EKLV_Packet() will continue to + generate BER encodings with a length greater than the specified minimum for + payloads that are larger than values encoded using the specified minimum. + + +2018-09-14 - 2.9.30 + o Fixes wrong MajorVersion in Preface + o Adds VideoLineMap also to RGBA essence descriptor + o Adds VideoLineMap to RGBA and CDCI descriptor only when option -l + is present (disputable - but distinguished value {0, 0} is not + allowed in closed and complete partitions) + o Fixes issue with IndexRate not set in AS-02 J2K files + o Additional fixes to minor version number in AS-02 partition packs + o CMake brought up to date + o Fixed erroneous WAV RF64 header interpretation + o ACES AS-02 ST 2065-5 wrapper + o ACES AS-02 ST 2065-5 unwrapper + o ST 2067-50 Subdescriptors support + o ST 2067-50 Target Frame wrapping support + o ST 2067-50 Target Frame unwrapping support + o Command line tools as-02-wrap, as-02-unwrap and as-02-info extended to + support ACES, App#5 subdescriptors and Target Frames + o Beta support for ST2065-5 AS_02 ACES wrapping and unwrapping including + ST 2067-50 Subdescriptors and Target Frame support + o Please report ACES-related issues to wolfgang.ruppel@hs-rm.de + + +2018-08-08 - 2.8.29 + o Modified AS_02::ST2052_TextParser::OpenRead signature + o Fixed partition version error in AS-02 interior body partitions + o Changed StartTimecode to 0 (zero) in the Source Package + o Remove use of BN_init in OpenSSL API + o XML parser now works correctly with Xerces-c 3.x + o Improved MCA sound field expression parser + o Added support for IMF Numbered Source Channel labels in MCA + o Added CLI switches for MCAAudioContentKind and MCAAudioElementKind + o Re-assigned asdcp-wrap option '-g' to '-x', added new option '-g' + o Added TLM marker check to j2c-test + o Added to kmrandgen options '-C', '-w', '-W' + o Added support for SMPTE RDD 47 "ISXD Track File" + o Added generic support for SMPTE RP 2057 "Text-Based Metadata Carriage in MXF" + o Re-factored AS-02 frame-wrap index write to use a common implementation + o Re-factored support for SMPTE ST 410 to use a common implementation (affects + AS-DCP and AS-02 timed-text MXF (SMPTE 429-5) + o Patched several ambiguous integer casts. + o Added new essence type identifiers ESS_AS02_ISXD and ESS_AS02_ACES + o Fixed a bug wherein the Generic Container data track clip was instead being + written as a DM track + o Fixed UL values DCDataDescriptor and ContainerConstraintSubDescriptor to have + a byte 6 value of 0x53 (Tag Set) instead of 0x07 (coding sentinel) + o Added UL values 468 - 511 to the dictionary (including added ACES UL values) + o Added ApplicationSchemes and ConformsToSpecifications to the Preface set + o Added default initializer to MXF::LineMapPair + o Added sets DescriptiveFramework, DescriptiveObject, TextBasedDMFramework, + TextBasedObject, GenericStreamTextBasedSet and ISXDDataEssenceDescriptor, + ACESPictureSubDescriptor, TargetFrameSubDescriptor + o Added ISXD support, options '-c', '-g', '-G', '-v', '-q', '-u' to as-02-wrap + o Added ISXD support and option '-g' to as-02-unwrap + o Cleaned up definition of UL WaveAudioDescriptor_PeakEnvelopeData (currently + unused) + o Moved ReferenceAudioAlignmentLevel from WaveAudioDescriptor to + GenericSoundEssenceDescriptor + + +2016-12-10 - MDD bug fix 2.7.19 + o The previous version (2.7.18) contained incorrect MDD.cpp and MDD.h + files which affect the PIMF and JP2KEssenceCompression labels. + + +2016-12-10 - bug fixes 2.7.18 + o Fixed *all* Partiton version numbers in AS-02 files (the previous attempt + only affected the header partition) + o Improved IMSC-1 profile detection. May not yet be perfect, experimentation + encouraged! + o Added IMF App2e UL values and new MXF data types ColorPrimary and + ThreeColorPrimaries (contributed by Schleich) + o Added picture descriptor elements MasteringDisplayPrimaries, + MasteringDisplayWhitePointChromaticity, MasteringDisplayMaximumLuminance, + and MasteringDisplayMinimumLuminance + o Added -o and -O options to as-02-wrap + o Fixed as-02-wrap option -p when making 4:4:4 files + o Simplified as-02-wrap syntax description + + +2016-12-01 - bug fixes 2.6.17 + o Fixed Partiton and Preface version numbers in AS-02 files + o Replaced WIN32 directory scanner with dirent_win.h + o The NamespaceURI property of AS-02 timed text files has been exposed in the API + and via as-02-wrap -P. This behavior replaces previous bad behavior, but puts + responsibility for selecting the correct value on the operator. + o Exposed CreatePNGNameId and CreateFontNameId subroutines in AS_02::TimedText + o Adjusted UUID generation based on PNG and font names to exclude paths by + inserting a call to PathBasename at each Id generation site + o Fixed AS-02 timed text index partition + o Fixed contents of generic partiton EssenceContainers property in AS-DCP timed + text files + o Added PixelLayout to RGBAEssenceDescriptor (contributed by Schleich) + o Cleared up MXFGCP1FrameWrappedPictureElement / MXFGCP1FrameWrappedPictureElement + ambiguity. PHDR continues to use MXFGCP1FrameWrappedPictureElement. + MXFGCI1FrameWrappedPictureElement is supported for interlace. + o Added support for 192, 200 and 240 fps images, includes 96, 100 and 120 fpe stereo + o Added missing MCA properties to MCALabelSubDescriptor (contributed by Ruppel) + o New MXF data type: LineMapPair + o Added default 0,0 VideoLineMap value when wrapping CDCI with as-02-wrap + o Added VideoLineMap property to GenericPictureEssenceDescriptor + o Added timed text unwrap support to as-02-unwrap (contributed by Ruppel) + o Added prototype PIDM dynamic metadata wrapping, config with --enable-phdr + (Not for production use, caveat emptor, not the droids, etc.) + + +2016-08-11 - bug fixes, 2.5.15 + + o Modified as-02-wrap to pass WhiteRefLev, BlackRefLev and ColorRange + (contributed by Elmer Musser / Rod Bogart) + o Fixed a bug in the index reader that allowed an out-of-bounds vector index + to be used. + o Modified the IndexEntry parser to ignore additional bytes belonging to slice + values. + + +2016-05-06 - bug fixes, 2.5.14 + + o Release 2.5.12 caused two problems with Atoms and DTS-X wrapping that are + addressed by this release. The UL values that were changed to correct the + DCData (ST 429-14) implementation had two unintended side-effects: + 1. v2.5.12 cannot read old DCData (and thus DTS-X) track files + 2. v2.5.12 creates broken Atmos track files (incorrect ULs) + The fix for this involved the following changes: + 1. ASDCP::DCData::(MXFReader|MXFWriter) are no longer base classes of + ASDCP::ATMOS::(MXFReader|MXFWriter). + 2. New UL values have been added to carry the original Atoms UL values: + a. DolbyAtmosDCDataWrappingFrame + b. DolbyAtmosDCDataEssence + c. DolbyAtmosDCDataDescriptor + 3. ASDCP::ATMOS::(MXFReader|MXFWriter) have been modified to use the + DolbyAtmosDCData* UL values. + 4. ASDCP::DCData::MXFReader will parse files having either DCData* or + DolbyAtmosDCData* UL values. + 5. ASDCP::DCData:: MXFWriter continues to use DCData* UL values from ST + 429-14 + o Some optional parameters of the MXF metadata packs were being erroneously + initialized with a value of zero (0), such as GenericPictureEssenceDescriptor + ::SignalStandard, GenericPictureEssenceDescriptor::SampledXOffset(0), etc. + o Added higher edit rates (96, 100, 120) to the cinema TimedText_Parser + + o Defined bool ASDCP::UL::operator<(const UL& rhs) const, which is needed to + carry out the version-insensitive lookup policy when searching for ULs in a + std::map<> of UL entries. + o New files: src/info.in src/CMakeLists.txt + o Removed filess: AS_DCP_DCData_internal.h + + +2016-03-17 - bug fixes, 2.5.12 + o Changed default UNIX file permissions to "666" + o Changed default UNIX file permissions to "777" + o Added missing initializer for caltime::offset + o Fixed UL values for Aux Data files (per ST 429-14) + o Added support for default TTML fonts (ST2052_TextParser) + o Added Solaris patch to KM_fileio (Thanks Mikey!) + o Fixed the version byte in UL DataEssenceCoding + o Fixed duplicate linkage error for symbol MIME2str + o Big patch from Wolfgang Ruppel: + o Corrected erroneous fixed-tag values in ActiveHeight, ActiveWidth, + ActiveXOffset, ActiveYOffset UL definitions. + o Provided a stub implementation for Kumu::DirScannerEx (A real + implementation will follow soon.) + o Added as-02-info program + o Added Seek() method to PCM parsers + o Added CMakeLists.txt + + +2015-11-10 - bug fixes, IMF text, pink noise, 2.5.11 + 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