README.md

   1
   2 # AS-DCP Lib
   3
   4 ## Introduction
   5
   6 The asdcplib library is an API and command-line tool set that offers
   7 access to files conforming to the sound and picture track file formats
   8 developed by the SMPTE Working Group DC28.20 (now TC 21DC).
   9
  10 Support has since been added for SMPTE ST 2067-5 "IMF Essence
  11 Component", AKA "AS-02", which was published and is maintained by
  12 SMPTE TC 35 PM.  The initial draft of this code was donated by
  13 Fraunhofer IIS and was created by Robert Scheler and Heiko Sparenberg.
  14 It carries additional copyright information which should be listed
  15 whenever you link the AS-02 elements of the library. Please look at
  16 the top of the AS-02 files to see this copyright information.
  17
  18 Support for ST 20XX OpenEXR was developed and contributed by Bjoern
  19 Stresing, Patrick Bichiou and Wolfgang Ruppel, supported by AMPAS.
  20 It carries additional copyright information which should be listed
  21 whenever you link the AS-02 elements of the library. Please look at
  22 the top of the AS-02 files to see this copyright information.
  23
  24 AS-02 support is carried in separate object modules, so unless you
  25 `#include <AS_02.h>` and link `libas-02.so` you are still using plain old
  26 asdcp.
  27
  28
  29 ## Documentation
  30
  31 This library is intended (but of course not limited) for use by
  32 developers of commercial D-Cinema and IMF products and for commercial
  33 mastering toolchains. The documentation is terse and sparse.
  34
  35 The API documentation is mostly in AS_DCP.h. and AS_02.h  Read those
  36 files for a detailed description of the library's capabilities. Read
  37 asdcp-*.cpp and as-02-*.cpp files for library usage examples. The
  38 command-line utilities all respond to -h.
  39
  40 Also, of course, the various SMPTE and ISO standards that underly all
  41 of this work should be well understood if you want to tinker with
  42 anything, or, in some cases, understand what properties are required
  43 in a particular supported use case (e.g., selecting audio channel labels.)
  44
  45
  46 ## CLI Programs
  47
  48 ### Standard Utilities
  49
  50 `asdcp-test` - DEPRECATED  Writes, reads and verifies AS-DCP (MXF) track files.
  51
  52 `asdcp-wrap` - Writes AS-DCP (MXF) track files.
  53
  54 `asdcp-unwrap` - Extracts essence from AS-DCP (MXF) track files.
  55
  56 `asdcp-info` - Displays information about AS-DCP (MXF) track files.
  57
  58 `asdcp-util` - Calculates digests and generates random numbers and UUIDs.
  59
  60 `as-02-wrap` - Writes AS-02 Essence Component files.
  61
  62 `as-02-unwrap` - Extracts essence from AS-02 Essence Component files.
  63
  64 `kmfilegen` - Writes and verifies large files using a platform-independent format. Use it to test issues related to large files.
  65
  66 `kmuuidgen`, `kmrandgen` - generate UUID values and random numbers.
  67
  68 `wavesplit` - Splits a WAVE file into two or more output files. Used  to untangle incorrectly-paired DCDM sound files.
  69
  70 `blackwave` - Write a WAVE file of zeros.
  71
  72 `pinkwave` - Write a WAVE file of SMPTE ST 2095 pink noise.
  73
  74 `j2c-test` - Displays information about JP2K codestreams.
  75
  76 ### PHDR
  77
  78 An experimental feature, Prototype for High Dynamic Range is a wrapper
  79 for the IMF application that allows JPEG-2000 codestreams to be paired
  80 with opaque blobs of metadata.  AS-02 support must be enabled to
  81 build this feature, so --enable-as-02 must be enabled if
  82 --enable-phdr is to be used.  The following executable programs will be
  83 built:
  84
  85 `phdr-wrap` - Writes AS-02 PHDR Essence Component files.
  86
  87 `phdr-unwrap` - Extracts essence from AS-02 PHDR Essence Component files.
  88
  89
  90 ## Historical Notes
  91
  92 This work was originally funded by Digital Cinema Initiatives, LLC
  93 (DCI). Subsequent efforts have been funded by Deluxe Laboratories,
  94 Doremi Labs, CineCert LLC, Avica Technology and others.
  95
  96 The asdcplib project was originally exchanged by FTP. The project was
  97 on [SourceForge](https://sourceforge.net/projects/asdcplib) between
  98 2005 and 2008, when it moved to a release-only distribution via
  99 [CineCert](https://www.cinecert.com/asdcplib/download). As of late
 100 February 2019, its new home is on [github](https://github.com/cinecert/asdcplib).
 101
 102 In the eraliest days, the project depended upon the
 103 [mxflib](http://sourceforge.net/projects/mxflib) project. Because of
 104 its focus on covering the whole of the MXF specifications, mxflib is
 105 considerably larger and more complex that what was required for the
 106 AS-DCP application. For this reason I developed a dedicated MXF
 107 implementation. Special thanks to Matt Beard and Oliver Morgan for
 108 their great work and support.
 109
 110 Thanks also to the members of the SMPTE DC28.20 packaging ad-hoc group
 111 and the members of the MXF Interop Initiative for their encouragement
 112 and support. Special thanks to Jim Whittlesey and Howard Lukk at DCI
 113 for proposing and supporting this project.