doc/mainpage.txt

   1 /*!
   2
   3 @mainpage libdcp
   4
   5 libdcp is a small library to create and read Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
   6
   7 Most of the hard work is done by a (slightly patched) version of asdcplib (http://www.cinecert.com/asdcplib/)
   8 which is included in the source distribution for libdcp.
   9
  10 libdcp is distributed under the GNU GPL.
  11
  12 Creating DCPs
  13 --
  14
  15 Typical use for creating DCPs might be:
  16 @code
  17 #include <libdcp/dcp.h>
  18 using namespace std;
  19
  20 libdcp::DCP dcp ("My Film DCP", "My Film", libdcp::DCP::FEATURE, 24, 50000);
  21
  22 vector<string> j2k_files;
  23 j2k_files.push_back ("1.j2c");
  24 ...
  25 j2k_files.push_back ("50000.j2c");
  26
  27 // These images are 1998x1080 pixels (DCI Flat)
  28 dcp.add_picture_asset (j2k_files, 1998, 1080);
  29
  30 vector<string> wav_files;
  31 wav_files.push_back ("L.wav");
  32 wav_files.push_back ("R.wav");
  33 wav_files.push_back ("C.wav");
  34 wav_files.push_back ("Lfe.wav");
  35 wav_files.push_back ("Ls.wav");
  36 wav_files.push_back ("Rs.wav");
  37 dcp.add_sound_asset (wav_files);
  38
  39 dcp.write_xml ();
  40
  41 @endcode
  42
  43 This will create a DCP at 24 frames per second with 50000 frames, writing
  44 data to a directory "My Film DCP", naming the DCP "My Film" and marking
  45 as a Feature.  We then add the picture and sound files (which creates
  46 MXF files inside the DCP directory) and then write the required XML files.
  47
  48 If you want to report progress for long jobs (add_picture_asset() can
  49 take a long time, in particular, as it must do a lot of disk I/O for
  50 large DCPs), connect to the libdcp::DCP::Progress signal and report its parameter
  51 to the user (it will range between 0 for 0% and 1 for 100%) using something like
  52
  53 @code
  54 void
  55 report (float p)
  56 {
  57    cout << "We are " << int (p * 100) << "% done.\n";
  58 }
  59
  60 dcp.Progress.connect (sigc::ptr_fun (&report));
  61 @endcode
  62
  63 If you can generate content paths algorithmically, you may prefer to do something
  64 like this:
  65
  66 @code
  67
  68 string
  69 j2k_path (int frame)
  70 {
  71         stringstream s;
  72         s << "my_j2ks/" << frame << ".j2c"
  73         return s.str ();
  74 }
  75
  76 string
  77 wav_path (libdcp::Channel channel)
  78 {
  79         switch (channel) {
  80         case LEFT:
  81                 return "left.wav";
  82         case RIGHT:
  83                 return "right.wav";
  84         }
  85
  86         return "";
  87 }
  88
  89 ...
  90
  91 // Our images are 1998x1080 (DCI Flat)
  92 dcp.add_picture_asset (sigc::ptr_fun (&j2k_path), 1998, 1080);
  93 // We have two sound channels
  94 dcp.add_sound_asset (sigc::ptr_fun (&wav_path), 2);
  95
  96 ...
  97
  98 @endcode
  99
 100 Reading existing DCPs
 101 --
 102
 103 Alternatively libdcp can be used to read existing DCPs and examine their content.  You
 104 might do
 105
 106 @code
 107 #include <libdcp/dcp.h>
 108 using namespace std;
 109
 110 libdcp::DCP dcp ("some-DCP-directory");
 111 @endcode
 112
 113 libdcp will look at the XML files that make up the DCP and find its assets.  You can then
 114 do things like
 115
 116 @code
 117 boost::shared_ptr<libdcp::PictureAsset> p = dcp.picture_asset ();
 118 boost::shared_ptr<libdcp::RGBAFrame> f = p->get_frame(42)->rgba_frame ();
 119 uint8_t* data = f->data ();
 120 int size = f->size ();
 121 @endcode
 122
 123 This will extract the image of frame 42 from the DCP and make its RGBA data available
 124 for examination.
 125
 126 Audio data is accessed in chunks equal in length to the duration of a video frame.  To
 127 get the audio that accompanies frame 66, you can do
 128
 129 @code
 130 boost::shared_ptr<libdcp::SoundAsset> s = dcp.sound_asset ();
 131 cout << "Sound has " << s->channels() << " channels at " << s->sampling_rate() << "Hz\n";
 132 boost::shared_ptr<libdcp::SoundFrame> f = s->get_frame(66);
 133 uint8_t* data = f->data ();
 134 int size = f->size ();
 135 @endcode
 136
 137 The returned data is interleaved 24-bit samples, so that
 138
 139 @code
 140 int left = data[0] | (data[1] << 8) | (data[2] << 16);
 141 data += 3;
 142 int right = data[0] | (data[1] << 8) | (data[2] << 16);
 143 data += 3;
 144 int centre = data[0] | (data[1] << 8) | (data[2] << 16);
 145 data += 3;
 146 int lfe = data[0] | (data[1] << 8) | (data[2] << 16);
 147 data += 3;
 148 int ls = data[0] | (data[1] << 8) | (data[2] << 16);
 149 data += 3;
 150 int rs = data[0] | (data[1] << 8) | (data[2] << 16);
 151 data += 3;
 152 @endcode
 153
 154 would obtain the first sample from each of the 6 channels for that frame.
 155
 156 Subtitles can be read using code like
 157
 158 @code
 159 boost::shared_ptr<SubtitleAsset> s = dcp.subtitle_asset ();
 160 list<boost::shared_ptr<libdcp::Text> > texts = s->subtitles_at (libdcp::Time (0, 3, 2, 5));
 161 @endcode
 162
 163 This returns the subtitles that should be shown at 3 minutes, 2
 164 seconds, 5 ticks (where 1 tick is 4ms) into the DCP.
 165
 166 */
 167
 168