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 ### Build Procedure Change for Auto Tools
  46
  47 You can ignore this if you are using CMake or one of the win32 build
  48 methods.
  49
  50 As of release 2.10.32 the release archive file will no longer contain
  51 the result of running `autoreconf`. This places a new requirement on
  52 the target platform, that `autoreconf` and friends are installed. This
  53 should not be an issue for most users. If it is, you can roll your own
  54 auto-tooled version by untarring the distribution and running
  55 `autoreconf` in its root directory as follows:
  56
  57 ```sh
  58 autoreconf -if
  59 ./configure --enable-freedist --enable-as-02
  60 make
  61 make dist
  62 ```
  63
  64 ## Libraries
  65
  66 `libkumu` - Platform compatibility layer.
  67
  68 `libasdcp` - SMPTE ST 429 (DCP) and JPEG Interop DCP.
  69
  70 `libas02` - SMPTE ST 2067 (IMF).
  71
  72 `libphdr` - Dolby Vision track file. Deprecated but maintained.
  73
  74
  75 ## CLI Programs
  76
  77 ### Standard Utilities
  78
  79 `asdcp-test` - DEPRECATED  Writes, reads and verifies AS-DCP (MXF) track files.
  80
  81 `asdcp-wrap` - Writes AS-DCP (MXF) track files.
  82
  83 `asdcp-unwrap` - Extracts essence from AS-DCP (MXF) track files.
  84
  85 `asdcp-info` - Displays information about AS-DCP (MXF) track files.
  86
  87 `asdcp-util` - Calculates digests and generates random numbers and UUIDs.
  88
  89 `as-02-wrap` - Writes AS-02 Essence Component files.
  90
  91 `as-02-unwrap` - Extracts essence from AS-02 Essence Component files.
  92
  93 `kmfilegen` - Writes and verifies large files using a platform-independent format. Use it to test issues related to large files.
  94
  95 `kmuuidgen`, `kmrandgen` - generate UUID values and random numbers.
  96
  97 `wavesplit` - Splits a WAVE file into two or more output files. Used  to untangle incorrectly-paired DCDM sound files.
  98
  99 `blackwave` - Write a WAVE file of zeros.
 100
 101 `pinkwave` - Write a WAVE file of SMPTE ST 2095 pink noise.
 102
 103 `j2c-test` - Displays information about JP2K codestreams.
 104
 105
 106 ### PHDR
 107
 108 An experimental feature, Prototype for High Dynamic Range is a wrapper
 109 for the IMF application that allows JPEG-2000 codestreams to be paired
 110 with opaque blobs of metadata.  AS-02 support must be enabled to
 111 build this feature, so --enable-as-02 must be enabled if
 112 --enable-phdr is to be used.  The following executable programs will be
 113 built:
 114
 115 `phdr-wrap` - Writes AS-02 PHDR Essence Component files.
 116
 117 `phdr-unwrap` - Extracts essence from AS-02 PHDR Essence Component files.
 118
 119
 120 ## Historical Notes
 121
 122 This work was originally funded by Digital Cinema Initiatives, LLC
 123 (DCI). Subsequent efforts have been funded by Deluxe Laboratories,
 124 Doremi Labs, CineCert LLC, Avica Technology and others.
 125
 126 The asdcplib project was originally exchanged by FTP. The project was
 127 on [SourceForge](https://sourceforge.net/projects/asdcplib) between
 128 2005 and 2008, when it moved to a release-only distribution via
 129 [CineCert](https://www.cinecert.com/asdcplib/download). As of late
 130 February 2019, its new home is on [github](https://github.com/cinecert/asdcplib).
 131
 132 In the earliest days, the project depended upon the
 133 [mxflib](http://sourceforge.net/projects/mxflib) project. Because of
 134 its focus on covering the whole of the MXF specifications, mxflib is
 135 considerably larger and more complex that what was required for the
 136 AS-DCP application. For this reason I developed a dedicated MXF
 137 implementation. Special thanks to Matt Beard and Oliver Morgan for
 138 their great work and support.
 139
 140 Thanks also to the members of the SMPTE DC28.20 packaging ad-hoc group
 141 and the members of the MXF Interop Initiative for their encouragement
 142 and support. Special thanks to Jim Whittlesey and Howard Lukk at DCI
 143 for proposing and supporting this project.