mediagst.h (5450B)
1 /* 2 This file is part of libextractor. 3 Copyright (C) 2026 Vidyut Samanta and Christian Grothoff 4 5 libextractor is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published 7 by the Free Software Foundation; either version 3, or (at your 8 option) any later version. 9 10 libextractor is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with libextractor; see the file COPYING. If not, write to the 17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 18 Boston, MA 02110-1301, USA. 19 */ 20 /** 21 * @file plugins/mediagst.h 22 * @brief plumbing between an extraction context and a GStreamer pipeline 23 * @author Christian Grothoff 24 * 25 * Shared by thumbnailgst and previewgst. Both drive a "playbin" reading 26 * from an "appsrc://" URI that we feed from the extraction context; 27 * playbin is used rather than a hand-built decodebin pipeline because it 28 * already knows how to pick a stream and how not to stall on the streams 29 * we are not interested in. 30 */ 31 #ifndef MEDIAGST_H 32 #define MEDIAGST_H 33 34 #include "extractor.h" 35 #include "mediautil.h" 36 37 #include <gst/gst.h> 38 39 /** 40 * Values of playbin's "flags" property. The enum is not part of any 41 * installed header, so we spell out the bits we use. 42 */ 43 #define EXTRACTOR_GST_PLAY_FLAG_VIDEO 0x00000001 44 45 /** 46 * Play the audio stream. 47 */ 48 #define EXTRACTOR_GST_PLAY_FLAG_AUDIO 0x00000002 49 50 51 /** 52 * State of a GStreamer pipeline reading from an extraction context. 53 */ 54 struct EXTRACTOR_GstIO 55 { 56 /** 57 * Extraction context we are reading from. 58 */ 59 struct EXTRACTOR_ExtractContext *ec; 60 61 /** 62 * Current read position in the file. 63 */ 64 uint64_t offset; 65 66 /** 67 * Size of the file, 0 if unknown. 68 */ 69 uint64_t length; 70 71 /** 72 * Serializes access to @e ec and @e offset: appsrc reads from 73 * GStreamer's streaming threads, EXTRACTOR_gst_keepalive_() from the 74 * plugin's thread. 75 */ 76 GMutex lock; 77 78 /** 79 * When EXTRACTOR_gst_keepalive_() last talked to the host, in 80 * microseconds of g_get_monotonic_time(). 81 */ 82 gint64 last_ping; 83 }; 84 85 86 /** 87 * Create a playbin that reads from @a ec, with the given sinks. The 88 * pipeline is returned in state NULL; the caller sets it to PAUSED. 89 * 90 * @param[out] io I/O state to initialize 91 * @param ec extraction context to read from 92 * @param flags value for playbin's "flags" property 93 * @param video_sink sink to use for video, consumed 94 * @param audio_sink sink to use for audio, consumed 95 * @return the pipeline, or NULL if GStreamer could not provide one 96 */ 97 GstElement * 98 EXTRACTOR_gst_playbin_ (struct EXTRACTOR_GstIO *io, 99 struct EXTRACTOR_ExtractContext *ec, 100 unsigned int flags, 101 GstElement *video_sink, 102 GstElement *audio_sink); 103 104 105 /** 106 * Create an appsrc that reads from @a ec (from the beginning), for use 107 * in a hand-built pipeline. 108 * 109 * @param[out] io I/O state to initialize; must outlive the element 110 * @param ec extraction context to read from 111 * @return the source, NULL if GStreamer could not provide one 112 */ 113 GstElement * 114 EXTRACTOR_gst_appsrc_ (struct EXTRACTOR_GstIO *io, 115 struct EXTRACTOR_ExtractContext *ec); 116 117 118 /** 119 * Show the host that we are still alive. Out of process, libextractor 120 * closes the channel of a plugin that has been silent (no meta data, no 121 * seek request) for 500 ms; a plugin that works for longer without 122 * touching the file -- decoding frames it already has, say -- must 123 * therefore make itself heard, which a no-op seek (`SEEK_CUR` by 0) 124 * does. Serialized with the streaming threads under @e io's lock and 125 * rate limited, so it can be called often. 126 * 127 * @param io I/O state of the pipeline 128 */ 129 void 130 EXTRACTOR_gst_keepalive_ (struct EXTRACTOR_GstIO *io); 131 132 133 /** 134 * Like EXTRACTOR_gst_wait_async_(), but calls EXTRACTOR_gst_keepalive_() 135 * while waiting. 136 * 137 * @param pipeline pipeline to watch 138 * @param timeout how long to wait, in nanoseconds 139 * @param io I/O state of the pipeline 140 * @return 1 if the pipeline is ready, 0 on error, EOS or timeout 141 */ 142 int 143 EXTRACTOR_gst_wait_async_alive_ (GstElement *pipeline, 144 GstClockTime timeout, 145 struct EXTRACTOR_GstIO *io); 146 147 148 /** 149 * Wait for @a pipeline to finish its current asynchronous state change. 150 * 151 * @param pipeline pipeline to watch 152 * @param timeout how long to wait, in nanoseconds 153 * @return 1 if the pipeline is ready, 0 on error, EOS or timeout 154 */ 155 int 156 EXTRACTOR_gst_wait_async_ (GstElement *pipeline, 157 GstClockTime timeout); 158 159 160 /** 161 * Determine where in the media we should start sampling: @a offset 162 * seconds in, but never past a third of the duration. 163 * 164 * @param pipeline prerolled pipeline 165 * @param offset desired position in seconds 166 * @param[out] duration set to the duration in nanoseconds, 0 if unknown 167 * @return position to sample at, in nanoseconds 168 */ 169 gint64 170 EXTRACTOR_gst_sample_position_ (GstElement *pipeline, 171 unsigned int offset, 172 gint64 *duration); 173 174 #endif 175 176 /* end of mediagst.h */