libextractor

mediautil.h (5987B)

---

 /*
      This file is part of libextractor.
      Copyright (C) 2026 Vidyut Samanta and Christian Grothoff
 
      libextractor is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
      by the Free Software Foundation; either version 3, or (at your
      option) any later version.
 
      libextractor is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      General Public License for more details.
 
      You should have received a copy of the GNU General Public License
      along with libextractor; see the file COPYING.  If not, write to the
      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
      Boston, MA 02110-1301, USA.
  */
 /**
  * @file plugins/mediautil.h
  * @brief helpers shared by the video thumbnail and audio preview plugins
  * @author Christian Grothoff
  *
  * The four media plugins (thumbnailffmpeg, thumbnailgst, previewopus and
  * previewgst) all have to do the same three boring things before they can
  * get to work: parse the plugin option string, make sure the input even
  * looks like media, and keep an eye on the clock.  This file is compiled
  * into each of them (plugins are modules and must not depend on each
  * other, so this is deliberately a source-level, not a library-level,
  * dependency).
  */
 #ifndef MEDIAUTIL_H
 #define MEDIAUTIL_H
 
 #include "extractor.h"
 
 /**
  * Maximum number of bytes we are willing to emit for a thumbnail.
  */
 #define EXTRACTOR_MEDIA_MAX_THUMBNAIL (100 * 1024)
 
 /**
  * Maximum number of bytes we are willing to emit for an audio preview.
  */
 #define EXTRACTOR_MEDIA_MAX_PREVIEW (64 * 1024)
 
 /**
  * Largest image we are willing to scale down, in pixels.  Guards against
  * absurd dimensions in a hostile file header.
  */
 #define EXTRACTOR_MEDIA_MAX_PIXELS (64 * 1024 * 1024)
 
 /**
  * Largest width or height we accept for the source video.
  */
 #define EXTRACTOR_MEDIA_MAX_DIMENSION 16384
 
 
 /**
  * Options a media plugin understands, as given in the plugin
  * configuration string, i.e. "thumbnailffmpeg(size=256,format=png)".
  */
 struct EXTRACTOR_MediaOptions
 {
   /**
    * Edge length of the box the thumbnail must fit into, in pixels.
    */
   unsigned int size;
 
   /**
    * Emit PNG instead of JPEG (option "format=png").
    */
   int png;
 
   /**
    * How many seconds into the media we would like to sample.
    */
   unsigned int offset;
 
   /**
    * Length of the audio preview in seconds.
    */
   unsigned int length;
 
   /**
    * Target bitrate of the Opus encoder, in bits per second.
    */
   unsigned int bitrate;
 
   /**
    * Wall clock budget for the entire extraction, in milliseconds.
    */
   unsigned int deadline;
 };
 
 
 /**
  * A wall clock deadline.
  */
 struct EXTRACTOR_MediaDeadline
 {
   /**
    * When we must be done, in milliseconds since some arbitrary epoch.
    */
   uint64_t expiration;
 };
 
 
 /**
  * Initialize @a opt with the defaults, then apply the comma-separated
  * "key=value" assignments from @a config.  Unknown keys and malformed
  * values are ignored; the resulting values are always in range.
  *
  * @param config configuration string of the plugin, may be NULL
  * @param[out] opt set to the resulting options
  */
 void
 EXTRACTOR_media_options_parse_ (const char *config,
                                 struct EXTRACTOR_MediaOptions *opt);
 
 
 /**
  * Check whether the input of @a ec looks like media we should touch,
  * using libmagic on the first few kilobytes.  Always leaves the
  * extraction context rewound to the beginning of the file.
  *
  * Handing arbitrary bytes to a media framework is expensive and grows
  * the attack surface for no gain, so both plugin families gate on this.
  *
  * @param ec extraction context to inspect
  * @param want_audio also accept "audio/*" (in addition to "video/*")
  * @return 1 if the input should be processed, 0 if not
  */
 int
 EXTRACTOR_media_is_media_ (struct EXTRACTOR_ExtractContext *ec,
                            int want_audio);
 
 
 /**
  * Start the clock.
  *
  * @param[out] dl deadline to initialize
  * @param ms budget in milliseconds from now
  */
 void
 EXTRACTOR_media_deadline_start_ (struct EXTRACTOR_MediaDeadline *dl,
                                  unsigned int ms);
 
 
 /**
  * Check whether the budget is used up.
  *
  * @param dl deadline to check
  * @return 1 if we are out of time
  */
 int
 EXTRACTOR_media_deadline_expired_ (const struct EXTRACTOR_MediaDeadline *dl);
 
 
 /**
  * Time left before @a dl expires.
  *
  * @param dl deadline to check
  * @return remaining milliseconds, 0 if expired
  */
 uint64_t
 EXTRACTOR_media_deadline_remaining_ (const struct EXTRACTOR_MediaDeadline *dl);
 
 
 /**
  * Compute the size of a thumbnail with the aspect ratio of a
  * @a width x @a height image that fits into a @a box x @a box square.
  * Never scales up.
  *
  * @param width width of the source image
  * @param height height of the source image
  * @param box edge length of the target square
  * @param[out] rwidth width of the thumbnail
  * @param[out] rheight height of the thumbnail
  * @return 1 on success, 0 if the source dimensions are unusable
  */
 int
 EXTRACTOR_media_thumbnail_size_ (unsigned int width,
                                  unsigned int height,
                                  unsigned int box,
                                  unsigned int *rwidth,
                                  unsigned int *rheight);
 
 
 /**
  * Apply a linear fade-in and fade-out to 16-bit signed mono PCM.
  * Without this, a preview cut out of the middle of a track starts and
  * ends with an audible click.
  *
  * @param[in,out] samples PCM data to modify
  * @param num_samples number of samples in @a samples
  * @param fade_samples length of each ramp in samples
  */
 void
 EXTRACTOR_media_fade_s16_ (int16_t *samples,
                            size_t num_samples,
                            size_t fade_samples);
 
 #endif
 
 /* end of mediautil.h */