libextractor

mediautil.h (11080B)

---

 /*
      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;
 
   /**
    * Language of the subtitle track to dump as SRT (option "srt:LANG"),
    * empty string if no subtitle dump was requested.
    */
   char srt_lang[16];
 
   /**
    * Number of tiles in the thumbnail gallery (option "gallery:N"),
    * 0 for a plain single thumbnail.
    */
   unsigned int gallery;
 };
 
 
 /**
  * Largest number of tiles in a gallery.
  */
 #define EXTRACTOR_MEDIA_MAX_GALLERY 100
 
 /**
  * Largest gallery sheet in pixels.  Far below #EXTRACTOR_MEDIA_MAX_PIXELS:
  * the sheet is encoded in one uninterruptible call, and a larger one
  * cannot be squeezed into #EXTRACTOR_MEDIA_MAX_GALLERY_BYTES anyway.
  * Tiles are scaled down to fit.
  */
 #define EXTRACTOR_MEDIA_MAX_GALLERY_PIXELS (4 * 1024 * 1024)
 
 /**
  * Maximum number of bytes we are willing to emit for a gallery.
  */
 #define EXTRACTOR_MEDIA_MAX_GALLERY_BYTES (4 * 1024 * 1024)
 
 /**
  * Maximum number of bytes we are willing to emit for an SRT dump.
  */
 #define EXTRACTOR_MEDIA_MAX_SRT (8 * 1024 * 1024)
 
 
 /**
  * Check whether the language tag @a have of a stream matches the
  * language @a want requested by the user.  Both may be ISO 639-1
  * ("de"), ISO 639-2/B ("ger") or ISO 639-2/T ("deu"), optionally with
  * a region ("de-AT", "de_AT"); comparison ignores case.
  *
  * @param want requested language
  * @param have language tag of the stream, may be NULL
  * @return 1 if they denote the same language, 0 if not
  */
 int
 EXTRACTOR_media_lang_matches_ (const char *want,
                                const char *have);
 
 
 /**
  * Check whether a frame shows basically nothing: at least 99% of its
  * pixels fall into a narrow color range in every channel (e.g. almost
  * all black, almost all white, a uniform color, a fade).
  *
  * @param rgb packed RGB24 pixels
  * @param width width in pixels
  * @param height height in pixels
  * @param stride bytes per row
  * @return 1 if the frame is (nearly) flat, 0 if it has content
  */
 int
 EXTRACTOR_media_frame_is_flat_ (const uint8_t *rgb,
                                 unsigned int width,
                                 unsigned int height,
                                 size_t stride);
 
 
 /**
  * Choose a grid for @a n tiles of @a tile_w x @a tile_h pixels such
  * that the entire sheet is as close to 16:9 as possible (ties are
  * broken towards fewer empty cells).
  *
  * @param n number of tiles, at least 1
  * @param tile_w width of one tile
  * @param tile_h height of one tile
  * @param[out] cols number of columns
  * @param[out] rows number of rows
  */
 void
 EXTRACTOR_media_gallery_layout_ (unsigned int n,
                                  unsigned int tile_w,
                                  unsigned int tile_h,
                                  unsigned int *cols,
                                  unsigned int *rows);
 
 
 /**
  * Time stamp in the gallery for tile @a i of @a n: the midpoints of
  * @a n equal slices of @a duration_ms.
  *
  * @param i tile index, in [0,n)
  * @param n number of tiles
  * @param duration_ms length of the media
  * @return position of tile @a i in milliseconds
  */
 uint64_t
 EXTRACTOR_media_gallery_time_ (unsigned int i,
                                unsigned int n,
                                uint64_t duration_ms);
 
 
 /**
  * An SRT file under construction.
  */
 struct EXTRACTOR_MediaSrt
 {
   /**
    * The text so far.
    */
   char *buf;
 
   /**
    * Number of bytes in @e buf.
    */
   size_t len;
 
   /**
    * Allocated size of @e buf.
    */
   size_t cap;
 
   /**
    * Number of cues written so far.
    */
   unsigned int count;
 
   /**
    * 1 if we hit #EXTRACTOR_MEDIA_MAX_SRT or ran out of memory.
    */
   int full;
 };
 
 
 /**
  * Append one cue to @a srt.  @a text may contain ASS dialogue lines
  * ("0,0,Default,,0,0,0,,Hello\\Nworld", as FFmpeg produces them) or
  * plain text; ASS override tags are removed, "\\N" becomes a line
  * break, invalid UTF-8 is replaced by '?', and empty lines inside the
  * cue are dropped.  Cues without text are ignored.
  *
  * @param srt file to append to
  * @param start_ms start of the cue in milliseconds
  * @param end_ms end of the cue in milliseconds
  * @param text text of the cue
  * @param text_len number of bytes in @a text
  * @param is_ass 1 if @a text is an ASS dialogue event (fields before
  *        the text are skipped), 0 if it is plain text
  */
 void
 EXTRACTOR_media_srt_add_ (struct EXTRACTOR_MediaSrt *srt,
                           uint64_t start_ms,
                           uint64_t end_ms,
                           const char *text,
                           size_t text_len,
                           int is_ass);
 
 
 /**
  * Emit @a srt as #EXTRACTOR_METATYPE_SUBTITLE_TEXT (if non-empty).
  *
  * @param srt file to emit
  * @param ec extraction context
  * @param plugin_name short name of the plugin
  * @return return value of `proc` (0 if nothing was emitted)
  */
 int
 EXTRACTOR_media_srt_emit_ (const struct EXTRACTOR_MediaSrt *srt,
                            struct EXTRACTOR_ExtractContext *ec,
                            const char *plugin_name);
 
 
 /**
  * Release @a srt.
  *
  * @param srt file to release
  */
 void
 EXTRACTOR_media_srt_clear_ (struct EXTRACTOR_MediaSrt *srt);
 
 
 /**
  * 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 */