src/verify.h

   1 /*
   2     Copyright (C) 2018-2021 Carl Hetherington <cth@carlh.net>
   3
   4     This file is part of libdcp.
   5
   6     libdcp is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 2 of the License, or
   9     (at your option) any later version.
  10
  11     libdcp is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with libdcp.  If not, see <http://www.gnu.org/licenses/>.
  18
  19     In addition, as a special exception, the copyright holders give
  20     permission to link the code of portions of this program with the
  21     OpenSSL library under certain conditions as described in each
  22     individual source file, and distribute linked combinations
  23     including the two.
  24
  25     You must obey the GNU General Public License in all respects
  26     for all of the code used other than OpenSSL.  If you modify
  27     file(s) with this exception, you may extend this exception to your
  28     version of the file(s), but you are not obligated to do so.  If you
  29     do not wish to do so, delete this exception statement from your
  30     version.  If you delete this exception statement from all source
  31     files in the program, then also delete it here.
  32 */
  33
  34
  35 /** @file  src/verify.h
  36  *  @brief dcp::verify() method and associated code
  37  */
  38
  39
  40 #ifndef LIBDCP_VERIFY_H
  41 #define LIBDCP_VERIFY_H
  42
  43
  44 #include <boost/filesystem.hpp>
  45 #include <boost/function.hpp>
  46 #include <boost/optional.hpp>
  47 #include <string>
  48 #include <vector>
  49
  50
  51 /* Something in windows.h defines this */
  52 #undef ERROR
  53
  54
  55 namespace dcp {
  56
  57
  58 class VerificationNote
  59 {
  60 public:
  61         /* I've been unable to make mingw happy with ERROR as a symbol, so
  62            I'm using a VERIFY_ prefix here.
  63         */
  64         enum class Type {
  65                 ERROR,
  66                 BV21_ERROR, ///< may not always be considered an error, but violates a "shall" requirement of Bv2.1
  67                 WARNING
  68         };
  69
  70         /** Codes for errors or warnings from verifying DCPs.
  71          *
  72          *  The names should (in general) answer the question "what is wrong?" with an answer that begins "There is a ..."
  73          *  e.g. "There is a INCORRECT_CPL_HASH"
  74          *       "There is a MISSING_ASSET"
  75          *
  76          *  In general the pattern should be <negative-adjective> <noun>.
  77          *  Some <negative-adjective>s are:
  78          *
  79          *  - INCORRECT: something, which could have any value, is wrong.
  80          *  - INVALID: something, which should only be one of a set of values, is not in the set, or some preformatted
  81          *             quantity (e.g. XML) is in the wrong format.
  82          *  - MISMATCHED: two things, which should be the same, are not.
  83          *  - EMPTY: something, which should have a value, has no value.
  84          *  - MISSING: something, which should be present, is not.
  85          *  - FAILED: some part of the verification failed in some serious way.
  86          *
  87          *  Comments should clarify meaning and also say which of the optional fields (e.g. file)
  88          *  are filled in when this code is used.
  89          */
  90         enum class Code {
  91                 /** An error when reading the DCP
  92                  *  note contains (probably technical) details
  93                  */
  94                 FAILED_READ,
  95                 /** The hash of the CPL in the PKL does not agree with the CPL file
  96                  *  note contains CPL ID
  97                  *  file contains CPL filename
  98                  */
  99                 MISMATCHED_CPL_HASHES,
 100                 /** Frame rate given in a reel for the main picture is not 24, 25, 30, 48, 50 or 60
 101                  *  note contains the invalid frame rate as "<numerator>/<denominator>"
 102                  */
 103                 INVALID_PICTURE_FRAME_RATE,
 104                 /** The hash of a main picture asset does not agree with the PKL file
 105                  *  file contains the picture asset filename
 106                  */
 107                 INCORRECT_PICTURE_HASH,
 108                 /** The hash of a main picture is different in the CPL and PKL
 109                  *  file contains the picture asset filename
 110                  */
 111                 MISMATCHED_PICTURE_HASHES,
 112                 /** The hash of a main sound asset does not agree with the PKL file
 113                  *  file contains the sound asset filename
 114                  */
 115                 INCORRECT_SOUND_HASH,
 116                 /** The hash of a main sound is different in the CPL and PKL
 117                  *  file contains the sound asset filename
 118                  */
 119                 MISMATCHED_SOUND_HASHES,
 120                 /** An assetmap's <Path> entry is empty. */
 121                 EMPTY_ASSET_PATH,
 122                 /** A file mentioned in an asset map cannot be found
 123                  *  file contains the filename that is missing
 124                  */
 125                 MISSING_ASSET,
 126                 /** The DCP contains both SMPTE and Interop-standard components */
 127                 MISMATCHED_STANDARD,
 128                 /** Some XML fails to validate against the XSD/DTD
 129                  *  note contains the (probably technical) details
 130                  *  file contains the invalid filename
 131                  *  line contains the line number
 132                  */
 133                 INVALID_XML,
 134                 /** No ASSETMAP{.xml} was found */
 135                 MISSING_ASSETMAP,
 136                 /** An asset's IntrinsicDuration is less than 1 second
 137                  *  note contains asset ID
 138                  */
 139                 INVALID_INTRINSIC_DURATION,
 140                 /** An asset's Duration is less than 1 second
 141                  *  note contains asset ID
 142                  */
 143                 INVALID_DURATION,
 144                 /** The JPEG2000 data in at least one picture frame is larger than the equivalent of 250Mbit/s
 145                  *  file contains the picture asset filename
 146                  */
 147                 INVALID_PICTURE_FRAME_SIZE_IN_BYTES,
 148                 /** The JPEG2000 data in at least one picture frame is larger than the equivalent of 230Mbit/s
 149                  *  file contains the picture asset filename
 150                  */
 151                 NEARLY_INVALID_PICTURE_FRAME_SIZE_IN_BYTES,
 152                 /** An asset that the CPL requires is not in this DCP; the DCP may be a VF
 153                  *  note contains the asset ID
 154                  */
 155                 EXTERNAL_ASSET,
 156                 /** DCP is Interop, not SMPTE [Bv2.1_6.1] */
 157                 INVALID_STANDARD,
 158                 /** A language or territory does not conform to RFC 5646 [Bv2.1_6.2.1].
 159                  *  note contains the invalid language
 160                  */
 161                 INVALID_LANGUAGE,
 162                 /** A picture asset does not have one of the required Bv2.1 sizes (in pixels) [Bv2.1_7.1].
 163                  *  note contains the incorrect size as "<width>x<height>"
 164                  *  file contains the asset filename
 165                  */
 166                 INVALID_PICTURE_SIZE_IN_PIXELS,
 167                 /** A picture asset is 2K but is not at 24, 25 or 48 fps as required by Bv2.1 [Bv2.1_7.1].
 168                  *  note contains the invalid frame rate as "<numerator>/<denominator>"
 169                  *  file contains the asset filename
 170                  */
 171                 INVALID_PICTURE_FRAME_RATE_FOR_2K,
 172                 /** A picture asset is 4K but is not at 24fps as required by Bv2.1 [Bv2.1_7.1]
 173                  *  note contains the invalid frame rate as "<numerator>/<denominator>"
 174                  *  file contains the asset filename
 175                  */
 176                 INVALID_PICTURE_FRAME_RATE_FOR_4K,
 177                 /** A picture asset is 4K but is 3D which is not allowed by Bv2.1 [Bv2.1_7.1]
 178                  *  note contains the invalid frame rate as "<numerator>/<denominator>"
 179                  *  file contains the asset filename
 180                  */
 181                 INVALID_PICTURE_ASSET_RESOLUTION_FOR_3D,
 182                 /** A closed caption's XML file is larger than 256KB [Bv2.1_7.2.1].
 183                  *  note contains the invalid size in bytes
 184                  *  file contains the asset filename
 185                  */
 186                 INVALID_CLOSED_CAPTION_XML_SIZE_IN_BYTES,
 187                 /** Any timed text asset's total files is larger than 115MB [Bv2.1_7.2.1]
 188                  *  note contains the invalid size in bytes
 189                  *  file contains the asset filename
 190                  */
 191                 INVALID_TIMED_TEXT_SIZE_IN_BYTES,
 192                 /** The total size of all a timed text asset's fonts is larger than 10MB [Bv2.1_7.2.1]
 193                  *  note contains the invalid size in bytes
 194                  *  file contains the asset filename
 195                  */
 196                 INVALID_TIMED_TEXT_FONT_SIZE_IN_BYTES,
 197                 /** Some SMPTE subtitle XML has no <Language> tag [Bv2.1_7.2.2]
 198                  *  file contains the asset filename
 199                  */
 200                 MISSING_SUBTITLE_LANGUAGE,
 201                 /** Not all subtitle assets specify the same <Language> tag [Bv2.1_7.2.2] */
 202                 MISMATCHED_SUBTITLE_LANGUAGES,
 203                 /** Some SMPTE subtitle XML has no <StartTime> tag [Bv2.1_7.2.3]
 204                  *  file contains the asset filename
 205                  */
 206                 MISSING_SUBTITLE_START_TIME,
 207                 /** Some SMPTE subtitle XML has a non-zero <StartTime> tag [Bv2.1_7.2.3]
 208                  *  file contains the asset filename
 209                  */
 210                 INVALID_SUBTITLE_START_TIME,
 211                 /** The first subtitle or closed caption happens before 4s into the first reel [Bv2.1_7.2.4] */
 212                 INVALID_SUBTITLE_FIRST_TEXT_TIME,
 213                 /** At least one subtitle is less than the minimum of 15 frames suggested by [Bv2.1_7.2.5] */
 214                 INVALID_SUBTITLE_DURATION,
 215                 /** At least one pair of subtitles are separated by less than the the minimum of 2 frames suggested by [Bv2.1_7.2.5] */
 216                 INVALID_SUBTITLE_SPACING,
 217                 /** There are more than 3 subtitle lines in at least one place [Bv2.1_7.2.7] */
 218                 INVALID_SUBTITLE_LINE_COUNT,
 219                 /** There are more than 52 characters in at least one subtitle line [Bv2.1_7.2.7] */
 220                 NEARLY_INVALID_SUBTITLE_LINE_LENGTH,
 221                 /** There are more than 79 characters in at least one subtitle line [Bv2.1_7.2.7] */
 222                 INVALID_SUBTITLE_LINE_LENGTH,
 223                 /** There are more than 3 closed caption lines in at least one place [Bv2.1_7.2.6] */
 224                 INVALID_CLOSED_CAPTION_LINE_COUNT,
 225                 /** There are more than 32 characters in at least one closed caption line [Bv2.1_7.2.6] */
 226                 INVALID_CLOSED_CAPTION_LINE_LENGTH,
 227                 /** The audio sampling rate must be 48kHz [Bv2.1_7.3].
 228                  *  note contains the invalid frame rate
 229                  *  file contains the asset filename
 230                  */
 231                 INVALID_SOUND_FRAME_RATE,
 232                 /** The CPL has no <AnnotationText> tag [Bv2.1_8.1]
 233                  *  note contains the CPL ID
 234                  *  file contains the CPL filename
 235                  */
 236                 MISSING_CPL_ANNOTATION_TEXT,
 237                 /** The <AnnotationText> is not the same as the <ContentTitleText> [Bv2.1_8.1]
 238                  *  note contains the CPL ID
 239                  *  file contains the CPL filename
 240                  */
 241                 MISMATCHED_CPL_ANNOTATION_TEXT,
 242                 /** At least one asset in a reel does not have the same duration as the others */
 243                 MISMATCHED_ASSET_DURATION,
 244                 /** If one reel has a MainSubtitle, all must have them */
 245                 MISSING_MAIN_SUBTITLE_FROM_SOME_REELS,
 246                 /** If one reel has at least one ClosedCaption, all reels must have the same number of ClosedCaptions */
 247                 MISMATCHED_CLOSED_CAPTION_ASSET_COUNTS,
 248                 /** MainSubtitle in reels must have <EntryPoint> [Bv2.1_8.3.2]
 249                  *  note contains the asset ID
 250                  */
 251                 MISSING_SUBTITLE_ENTRY_POINT,
 252                 /** MainSubtitle <EntryPoint> must be zero [Bv2.1_8.3.2]
 253                  *  note contains the asset ID
 254                  */
 255                 INCORRECT_SUBTITLE_ENTRY_POINT,
 256                 /** Closed caption in reels must have <EntryPoint> [Bv2.1_8.3.2]
 257                  *  note contains the asset ID
 258                  */
 259                 MISSING_CLOSED_CAPTION_ENTRY_POINT,
 260                 /** Closed caption MainSubtitle <EntryPoint> must be zero [Bv2.1_8.3.2]
 261                  *  note contains the asset ID
 262                  */
 263                 INCORRECT_CLOSED_CAPTION_ENTRY_POINT,
 264                 /** <Hash> must be present for assets in CPLs
 265                  * note contains the asset ID
 266                  */
 267                 MISSING_HASH,
 268                 /** If ContentKind is Feature there must be a FFEC marker */
 269                 MISSING_FFEC_IN_FEATURE,
 270                 /** If ContentKind is Feature there must be a FFMC marker */
 271                 MISSING_FFMC_IN_FEATURE,
 272                 /** There should be a FFOC */
 273                 MISSING_FFOC,
 274                 /** There should be a LFOC */
 275                 MISSING_LFOC,
 276                 /** The FFOC should be 1
 277                  *  note contains the incorrect value.
 278                  */
 279                 INCORRECT_FFOC,
 280                 /** The LFOC should be the last frame in the reel
 281                  *  note contains the incorrect value
 282                  */
 283                 INCORRECT_LFOC,
 284                 /** There must be a <CompositionMetadataAsset>
 285                  *  note contains the CPL ID
 286                  *  file contains the CPL filename
 287                  */
 288                 MISSING_CPL_METADATA,
 289                 /** CPL metadata should contain <VersionNumber> of 1, at least
 290                  *  note contains the CPL ID
 291                  *  file contains the CPL filename
 292                  */
 293                 MISSING_CPL_METADATA_VERSION_NUMBER,
 294                 /** There must be an <ExtensionMetadata> in <CompositionMetadataAsset> [Bv2.1_8.6.3]
 295                  *  note contains the CPL ID
 296                  *  file contains the CPL filename
 297                  */
 298                 MISSING_EXTENSION_METADATA,
 299                 /** <ExtensionMetadata> must have a particular form [Bv2.1_8.6.3]
 300                  *  note contains details of what's wrong
 301                  *  file contains the CPL filename
 302                  */
 303                 INVALID_EXTENSION_METADATA,
 304                 /** CPLs containing encrypted content must be signed [Bv2.1_8.7]
 305                  *  note contains the CPL ID
 306                  *  file contains the CPL filename
 307                  */
 308                 UNSIGNED_CPL_WITH_ENCRYPTED_CONTENT,
 309                 /** PKLs containing encrypted content must be signed [Bv2.1_8.7]
 310                  *  note contains the PKL ID
 311                  *  file contains the PKL filename
 312                  */
 313                 UNSIGNED_PKL_WITH_ENCRYPTED_CONTENT,
 314                 /** If a PKL has one CPL its <ContentTitleText> must be the same as the PKL's <AnnotationText>.
 315                  *  note contains the PKL ID
 316                  *  file contains the PKL filename
 317                  */
 318                 MISMATCHED_PKL_ANNOTATION_TEXT_WITH_CPL,
 319                 /** If any content is encrypted, everything must be encrypted */
 320                 PARTIALLY_ENCRYPTED,
 321                 /** General error from our JPEG2000 codestream verification
 322                  *  note contains details
 323                  */
 324                 INVALID_JPEG2000_CODESTREAM,
 325                 /** Invalid number of guard bits in a 2K JPEG2000 stream (should be 1) [Bv2.1_10.2.1]
 326                  *  note contains the number of guard bits
 327                  */
 328                 INVALID_JPEG2000_GUARD_BITS_FOR_2K,
 329                 /** Invalid number of guard bits in a 4K JPEG2000 stream (should be 2) [Bv2.1_10.2.1]
 330                  *  note contains the number of guard bits
 331                  */
 332                 INVALID_JPEG2000_GUARD_BITS_FOR_4K,
 333                 /** JPEG2000 tile size is not the same as the image size [Bv2.1_10.2.1] */
 334                 INVALID_JPEG2000_TILE_SIZE,
 335                 /** JPEG2000 code block width is not 32 [Bv2.1_10.2.1]
 336                  *  note contains the code block width
 337                  */
 338                 INVALID_JPEG2000_CODE_BLOCK_WIDTH,
 339                 /** JPEG2000 code block height is not 32 [Bv2.1_10.2.1]
 340                  *  note contains the code block height
 341                  */
 342                 INVALID_JPEG2000_CODE_BLOCK_HEIGHT,
 343                 /** There must be no POC markers in a 2K codestream [Bv2.1_10.2.1]
 344                  *  note contains the number of POC markers found
 345                  */
 346                 INCORRECT_JPEG2000_POC_MARKER_COUNT_FOR_2K,
 347                 /** There must be exactly one POC marker in a 4K codestream [Bv2.1_10.2.1]
 348                  *  note contains the number of POC markers found
 349                  */
 350                 INCORRECT_JPEG2000_POC_MARKER_COUNT_FOR_4K,
 351                 /** A POC marker has incorrect content [Bv2.1_10.2.1]
 352                  *  note contains details
 353                  */
 354                 INCORRECT_JPEG2000_POC_MARKER,
 355                 /** A POC marker was found outside the main head [Bv2.1_10.2.1] */
 356                 INVALID_JPEG2000_POC_MARKER_LOCATION,
 357                 /** Invalid number of tile parts for 2K JPEG2000 stream (should be 3) [Bv2.1_10.2.1]
 358                  *  note contains the number of tile parts
 359                  */
 360                 INVALID_JPEG2000_TILE_PARTS_FOR_2K,
 361                 /** Invalid number of tile parts for 4K JPEG2000 stream (should be 6) [Bv2.1_10.2.1]
 362                  *  note contains the number of tile parts
 363                  */
 364                 INVALID_JPEG2000_TILE_PARTS_FOR_4K,
 365                 /** No TLM marker was found [Bv2.1_10.2.1] */
 366                 MISSING_JPEG200_TLM_MARKER,
 367         };
 368
 369         VerificationNote (Type type, Code code)
 370                 : _type (type)
 371                 , _code (code)
 372         {}
 373
 374         VerificationNote (Type type, Code code, std::string note)
 375                 : _type (type)
 376                 , _code (code)
 377                 , _note (note)
 378         {}
 379
 380         VerificationNote (Type type, Code code, boost::filesystem::path file)
 381                 : _type (type)
 382                 , _code (code)
 383                 , _file (file)
 384         {}
 385
 386         VerificationNote (Type type, Code code, std::string note, boost::filesystem::path file)
 387                 : _type (type)
 388                 , _code (code)
 389                 , _note (note)
 390                 , _file (file)
 391         {}
 392
 393         VerificationNote (Type type, Code code, std::string note, boost::filesystem::path file, uint64_t line)
 394                 : _type (type)
 395                 , _code (code)
 396                 , _note (note)
 397                 , _file (file)
 398                 , _line (line)
 399         {}
 400
 401         Type type () const {
 402                 return _type;
 403         }
 404
 405         Code code () const {
 406                 return _code;
 407         }
 408
 409         boost::optional<std::string> note () const {
 410                 return _note;
 411         }
 412
 413         boost::optional<boost::filesystem::path> file () const {
 414                 return _file;
 415         }
 416
 417         boost::optional<uint64_t> line () const {
 418                 return _line;
 419         }
 420
 421 private:
 422         Type _type;
 423         Code _code;
 424         /** Further information about the error, if applicable */
 425         boost::optional<std::string> _note;
 426         /** Path of file containing the error, if applicable */
 427         boost::optional<boost::filesystem::path> _file;
 428         /** Error line number within _file, if applicable */
 429         boost::optional<uint64_t> _line;
 430 };
 431
 432
 433 std::vector<VerificationNote> verify (
 434         std::vector<boost::filesystem::path> directories,
 435         boost::function<void (std::string, boost::optional<boost::filesystem::path>)> stage,
 436         boost::function<void (float)> progress,
 437         boost::filesystem::path xsd_dtd_directory
 438         );
 439
 440 std::string note_to_string (dcp::VerificationNote note);
 441
 442 bool operator== (dcp::VerificationNote const& a, dcp::VerificationNote const& b);
 443
 444 std::ostream& operator<<(std::ostream& s, dcp::VerificationNote const& note);
 445
 446
 447 }
 448
 449
 450 #endif