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<Reel> reel = dcp.reels.front ();
 118 boost::shared_ptr<libdcp::PictureAsset> p = reel->main_picture ();
 119 boost::shared_ptr<libdcp::MonoPictureAsset> mp = boost::dynamic_pointer_cast<libdcp::MonoPictureAsset> (p);
 120 boost::shared_ptr<libdcp::ARGBFrame> f = mp->get_frame(42)->argb_frame ();
 121 uint8_t* data = f->data ();
 122 int size = f->size ();
 123 @endcode
 124
 125 This will extract the image of frame 42 from the first reel of the DCP and make its ARGB data available
 126 for examination.  We have to do a <code>dynamic_pointer_cast</code> from <code>libdcp::PictureAsset</code>
 127 to <code>libdcp::MonoPictureAsset</code>, as the picture asset may be either 2D (monoscopic) or 3D (stereoscopic).
 128
 129 Audio data is accessed in chunks equal in length to the duration of a video frame.  To
 130 get the audio that accompanies frame 66, you can do
 131
 132 @code
 133 boost::shared_ptr<libdcp::SoundAsset> s = reel->main_sound ();
 134 cout << "Sound has " << s->channels() << " channels at " << s->sampling_rate() << "Hz\n";
 135 boost::shared_ptr<libdcp::SoundFrame> f = s->get_frame(66);
 136 uint8_t* data = f->data ();
 137 int size = f->size ();
 138 @endcode
 139
 140 The returned data are interleaved 24-bit samples, so that
 141
 142 @code
 143 int left = data[0] | (data[1] << 8) | (data[2] << 16);
 144 data += 3;
 145 int right = data[0] | (data[1] << 8) | (data[2] << 16);
 146 data += 3;
 147 int centre = data[0] | (data[1] << 8) | (data[2] << 16);
 148 data += 3;
 149 int lfe = data[0] | (data[1] << 8) | (data[2] << 16);
 150 data += 3;
 151 int ls = data[0] | (data[1] << 8) | (data[2] << 16);
 152 data += 3;
 153 int rs = data[0] | (data[1] << 8) | (data[2] << 16);
 154 data += 3;
 155 @endcode
 156
 157 would obtain the first sample from each of the 6 channels for that frame.
 158
 159 Subtitles can be read using code like
 160
 161 @code
 162 boost::shared_ptr<SubtitleAsset> s = dcp.subtitle_asset ();
 163 list<boost::shared_ptr<libdcp::Text> > texts = s->subtitles_at (libdcp::Time (0, 3, 2, 5));
 164 @endcode
 165
 166 This returns the subtitles that should be shown at 3 minutes, 2
 167 seconds, 5 ticks (where 1 tick is 4ms) into the DCP.
 168
 169 */
 170
 171