1 /** 2 * 3 * Copyright 2016-2020 Netflix, Inc. 4 * 5 * Licensed under the BSD+Patent License (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * https://opensource.org/licenses/BSDplusPatent 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #ifndef __VMAF_H__ 20 #define __VMAF_H__ 21 22 #include <stdint.h> 23 #include <stdio.h> 24 25 #include "libvmaf/compute_vmaf.h" 26 #include "libvmaf/model.h" 27 #include "libvmaf/picture.h" 28 #include "libvmaf/feature.h" 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 enum VmafLogLevel { 35 VMAF_LOG_LEVEL_NONE = 0, 36 VMAF_LOG_LEVEL_ERROR, 37 VMAF_LOG_LEVEL_WARNING, 38 VMAF_LOG_LEVEL_INFO, 39 VMAF_LOG_LEVEL_DEBUG, 40 }; 41 42 enum VmafOutputFormat { 43 VMAF_OUTPUT_FORMAT_NONE = 0, 44 VMAF_OUTPUT_FORMAT_XML, 45 VMAF_OUTPUT_FORMAT_JSON, 46 VMAF_OUTPUT_FORMAT_CSV, 47 VMAF_OUTPUT_FORMAT_SUB, 48 }; 49 50 enum VmafPoolingMethod { 51 VMAF_POOL_METHOD_UNKNOWN = 0, 52 VMAF_POOL_METHOD_MIN, 53 VMAF_POOL_METHOD_MAX, 54 VMAF_POOL_METHOD_MEAN, 55 VMAF_POOL_METHOD_HARMONIC_MEAN, 56 VMAF_POOL_METHOD_NB 57 }; 58 59 typedef struct VmafConfiguration { 60 enum VmafLogLevel log_level; 61 unsigned n_threads; 62 unsigned n_subsample; 63 uint64_t cpumask; 64 } VmafConfiguration; 65 66 typedef struct VmafContext VmafContext; 67 68 /** 69 * Allocate and open a VMAF instance. 70 * 71 * @param vmaf The VMAF instance to open. 72 * To be used in further libvmaf api calls. 73 * $vmaf will be set to the allocated context. 74 * Context should be cleaned up with `vmaf_close()` when finished. 75 * 76 * @param cfg Configuration parameters. 77 * 78 * 79 * @return 0 on success, or < 0 (a negative errno code) on error. 80 */ 81 int vmaf_init(VmafContext **vmaf, VmafConfiguration cfg); 82 83 /** 84 * Register feature extractors required by a specific `VmafModel`. 85 * This may be called multiple times using different models. 86 * In this case, the registered feature extractors will form a set, and any 87 * features required by multiple models will only be extracted once. 88 * 89 * @param vmaf The VMAF context allocated with `vmaf_init()`. 90 * 91 * @param model Opaque model context. 92 * 93 * 94 * @return 0 on success, or < 0 (a negative errno code) on error. 95 */ 96 int vmaf_use_features_from_model(VmafContext *vmaf, VmafModel *model); 97 98 /** 99 * Register feature extractors required by a specific `VmafModelCollection` 100 * Like `vmaf_use_features_from_model()`, this function may be called 101 * multiple times using different model collections. 102 * 103 * @param vmaf The VMAF context allocated with `vmaf_init()`. 104 * 105 * @param model_collection Opaque model collection context. 106 * 107 * 108 * @return 0 on success, or < 0 (a negative errno code) on error. 109 */ 110 int vmaf_use_features_from_model_collection(VmafContext *vmaf, 111 VmafModelCollection *model_collection); 112 113 /** 114 * Register specific feature extractor. 115 * Useful when a specific/additional feature is required, usually one which 116 * is not already provided by a model via `vmaf_use_features_from_model()`. 117 * This may be called multiple times. `VmafContext` will take ownership of the 118 * `VmafFeatureDictionary` (`opts_dict`). Use `vmaf_feature_dictionary_free()` 119 * only in the case of failure. 120 * 121 * @param vmaf The VMAF context allocated with `vmaf_init()`. 122 * 123 * @param feature_name Name of feature. 124 * 125 * @param opts_dict Feature extractor options set via 126 * `vmaf_feature_dictionary_set()`. If no special options 127 * are required this parameter can be set to NULL. 128 * 129 * @return 0 on success, or < 0 (a negative errno code) on error. 130 */ 131 int vmaf_use_feature(VmafContext *vmaf, const char *feature_name, 132 VmafFeatureDictionary *opts_dict); 133 134 /** 135 * Import an external feature score. 136 * Useful when pre-computed feature scores are available. 137 * Also useful in the case where there is no libvmaf feature extractor 138 * implementation for a required feature. 139 * 140 * @param vmaf The VMAF context allocated with `vmaf_init()`. 141 * 142 * @param feature_name Name of feature. 143 * 144 * @param value Score. 145 * 146 * @param index Picture index. 147 * 148 * 149 * @return 0 on success, or < 0 (a negative errno code) on error. 150 */ 151 int vmaf_import_feature_score(VmafContext *vmaf, const char *feature_name, 152 double value, unsigned index); 153 154 /** 155 * Read a pair of pictures and queue them for eventual feature extraction. 156 * This should be called after feature extractors are registered via 157 * `vmaf_use_features_from_model()` and/or `vmaf_use_feature()`. 158 * `VmafContext` will take ownership of both `VmafPicture`s (`ref` and `dist`) 159 * and `vmaf_picture_unref()`. 160 * 161 * When you're done reading pictures call this function again with both `ref` 162 * and `dist` set to NULL to flush all feature extractors. 163 * 164 * @param vmaf The VMAF context allocated with `vmaf_init()`. 165 * 166 * @param ref Reference picture. 167 * 168 * @param dist Distorted picture. 169 * 170 * @param index Picture index. 171 * 172 * 173 * @return 0 on success, or < 0 (a negative errno code) on error. 174 */ 175 int vmaf_read_pictures(VmafContext *vmaf, VmafPicture *ref, VmafPicture *dist, 176 unsigned index); 177 178 /** 179 * Predict VMAF score at specific index. 180 * 181 * @param vmaf The VMAF context allocated with `vmaf_init()`. 182 * 183 * @param model Opaque model context. 184 * 185 * @param index Picture index. 186 * 187 * @param score Predicted score. 188 * 189 * 190 * @return 0 on success, or < 0 (a negative errno code) on error. 191 */ 192 int vmaf_score_at_index(VmafContext *vmaf, VmafModel *model, double *score, 193 unsigned index); 194 195 /** 196 * Predict VMAF score at specific index, using a model collection. 197 * 198 * @param vmaf The VMAF context allocated with `vmaf_init()`. 199 * 200 * @param model_collection Opaque model collection context. 201 * 202 * @param index Picture index. 203 * 204 * @param score Predicted score. 205 * 206 * 207 * @return 0 on success, or < 0 (a negative errno code) on error. 208 */ 209 int vmaf_score_at_index_model_collection(VmafContext *vmaf, 210 VmafModelCollection *model_collection, 211 VmafModelCollectionScore *score, 212 unsigned index); 213 214 /** 215 * Fetch feature score at specific index. 216 * 217 * @param vmaf The VMAF context allocated with `vmaf_init()`. 218 * 219 * @param feature_name Name of the feature to fetch. 220 * 221 * @param index Picture index. 222 * 223 * @param score Score. 224 * 225 * 226 * @return 0 on success, or < 0 (a negative errno code) on error. 227 */ 228 int vmaf_feature_score_at_index(VmafContext *vmaf, const char *feature_name, 229 double *score, unsigned index); 230 231 /** 232 * Pooled VMAF score for a specific interval. 233 * 234 * @param vmaf The VMAF context allocated with `vmaf_init()`. 235 * 236 * @param model Opaque model context. 237 * 238 * @param pool_method Temporal pooling method to use. 239 * 240 * @param score Pooled score. 241 * 242 * @param index_low Low picture index of pooling interval. 243 * 244 * @param index_high High picture index of pooling interval. 245 * 246 * 247 * @return 0 on success, or < 0 (a negative errno code) on error. 248 */ 249 int vmaf_score_pooled(VmafContext *vmaf, VmafModel *model, 250 enum VmafPoolingMethod pool_method, double *score, 251 unsigned index_low, unsigned index_high); 252 253 /** 254 * Pooled VMAF score for a specific interval, using a model collection. 255 * 256 * @param vmaf The VMAF context allocated with `vmaf_init()`. 257 * 258 * @param model_collection Opaque model collection context. 259 * 260 * @param pool_method Temporal pooling method to use. 261 * 262 * @param score Pooled score. 263 * 264 * @param index_low Low picture index of pooling interval. 265 * 266 * @param index_high High picture index of pooling interval. 267 * 268 * 269 * @return 0 on success, or < 0 (a negative errno code) on error. 270 */ 271 int vmaf_score_pooled_model_collection(VmafContext *vmaf, 272 VmafModelCollection *model_collection, 273 enum VmafPoolingMethod pool_method, 274 VmafModelCollectionScore *score, 275 unsigned index_low, unsigned index_high); 276 277 /** 278 * Pooled feature score for a specific interval. 279 * 280 * @param vmaf The VMAF context allocated with `vmaf_init()`. 281 * 282 * @param feature_name Name of the feature to fetch. 283 * 284 * @param pool_method Temporal pooling method to use. 285 * 286 * @param score Pooled score. 287 * 288 * @param index_low Low picture index of pooling interval. 289 * 290 * @param index_high High picture index of pooling interval. 291 * 292 * 293 * @return 0 on success, or < 0 (a negative errno code) on error. 294 */ 295 int vmaf_feature_score_pooled(VmafContext *vmaf, const char *feature_name, 296 enum VmafPoolingMethod pool_method, double *score, 297 unsigned index_low, unsigned index_high); 298 299 /** 300 * Close a VMAF instance and free all associated memory. 301 * 302 * @param vmaf The VMAF instance to close. 303 * 304 * 305 * @return 0 on success, or < 0 (a negative errno code) on error. 306 */ 307 int vmaf_close(VmafContext *vmaf); 308 309 /** 310 * Write VMAF stats to an output file. 311 * 312 * @param vmaf The VMAF context allocated with `vmaf_init()`. 313 * 314 * @param output_path Output file path. 315 * 316 * @param fmt Output file format. 317 * See `enum VmafOutputFormat` for options. 318 * 319 * 320 * @return 0 on success, or < 0 (a negative errno code) on error. 321 */ 322 int vmaf_write_output(VmafContext *vmaf, const char *output_path, 323 enum VmafOutputFormat fmt); 324 325 /** 326 * Get libvmaf version. 327 */ 328 const char *vmaf_version(void); 329 330 #ifdef __cplusplus 331 } 332 #endif 333 334 #endif /* __VMAF_H__ */ 335