FFmpeg
subtitles.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2012 Clément Bœsch
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg 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 GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 #ifndef AVFORMAT_SUBTITLES_H
22 #define AVFORMAT_SUBTITLES_H
23 
24 #include <stdint.h>
25 #include <stddef.h>
26 #include "avformat.h"
27 #include "libavutil/bprint.h"
28 
29 enum sub_sort {
30  SUB_SORT_TS_POS = 0, ///< sort by timestamps, then position
31  SUB_SORT_POS_TS, ///< sort by position, then timestamps
32 };
33 
35  FF_UTF_8, // or other 8 bit encodings
38 };
39 
40 typedef struct {
41  int type;
43  unsigned char buf[8];
44  int buf_pos, buf_len;
46 } FFTextReader;
47 
48 /**
49  * Initialize the FFTextReader from the given AVIOContext. This function will
50  * read some bytes from pb, and test for UTF-8 or UTF-16 BOMs. Further accesses
51  * to FFTextReader will read more data from pb.
52  * If s is not NULL, the user will be warned if a UTF-16 conversion takes place.
53  *
54  * The purpose of FFTextReader is to transparently convert read data to UTF-8
55  * if the stream had a UTF-16 BOM.
56  *
57  * @param s Pointer to provide av_log context
58  * @param r object which will be initialized
59  * @param pb stream to read from (referenced as long as FFTextReader is in use)
60  */
61 void ff_text_init_avio(void *s, FFTextReader *r, AVIOContext *pb);
62 
63 /**
64  * Similar to ff_text_init_avio(), but sets it up to read from a bounded buffer.
65  *
66  * @param r object which will be initialized
67  * @param buf buffer to read from (referenced as long as FFTextReader is in use)
68  * @param size size of buf
69  */
70 void ff_text_init_buf(FFTextReader *r, void *buf, size_t size);
71 
72 /**
73  * Return the byte position of the next byte returned by ff_text_r8(). For
74  * UTF-16 source streams, this will return the original position, but it will
75  * be incorrect if a codepoint was only partially read with ff_text_r8().
76  */
77 int64_t ff_text_pos(FFTextReader *r);
78 
79 /**
80  * Return the next byte. The return value is always 0 - 255. Returns 0 on EOF.
81  * If the source stream is UTF-16, this reads from the stream converted to
82  * UTF-8. On invalid UTF-16, 0 is returned.
83  */
85 
86 /**
87  * Return non-zero if EOF was reached.
88  */
90 
91 /**
92  * Like ff_text_r8(), but don't remove the byte from the buffer.
93  */
95 
96 /**
97  * Read the given number of bytes (in UTF-8). On error or EOF, \0 bytes are
98  * written.
99  */
100 void ff_text_read(FFTextReader *r, char *buf, size_t size);
101 
102 typedef struct {
103  AVPacket **subs; ///< array of subtitles packets
104  int nb_subs; ///< number of subtitles packets
105  int allocated_size; ///< allocated size for subs
106  int current_sub_idx; ///< current position for the read packet callback
107  enum sub_sort sort; ///< sort method to use when finalizing subtitles
108  int keep_duplicates; ///< set to 1 to keep duplicated subtitle events
110 
111 /**
112  * Insert a new subtitle event.
113  *
114  * @param event the subtitle line, may not be zero terminated
115  * @param len the length of the event (in strlen() sense, so without '\0')
116  * @param merge set to 1 if the current event should be concatenated with the
117  * previous one instead of adding a new entry, 0 otherwise
118  */
120  const uint8_t *event, size_t len, int merge);
121 
122 /**
123  * Set missing durations, sort subtitles by PTS (and then byte position), and
124  * drop duplicated events.
125  */
126 void ff_subtitles_queue_finalize(void *log_ctx, FFDemuxSubtitlesQueue *q);
127 
128 /**
129  * Generic read_packet() callback for subtitles demuxers using this queue
130  * system.
131  */
133 
134 /**
135  * Update current_sub_idx to emulate a seek. Except the first parameter, it
136  * matches AVInputFormat->read_seek2 prototypes.
137  */
139  int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
140 
141 /**
142  * Remove and destroy all the subtitles packets.
143  */
145 
147 
148 int ff_subtitles_read_seek(AVFormatContext *s, int stream_index,
149  int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
150 
152 
153 /**
154  * SMIL helper to load next chunk ("<...>" or untagged content) in buf.
155  *
156  * @param c cached character, to avoid a backward seek
157  */
158 int ff_smil_extract_next_text_chunk(FFTextReader *tr, AVBPrint *buf, char *c);
159 
160 /**
161  * SMIL helper to point on the value of an attribute in the given tag.
162  *
163  * @param s SMIL tag ("<...>")
164  * @param attr the attribute to look for
165  */
166 const char *ff_smil_get_attr_ptr(const char *s, const char *attr);
167 
168 /**
169  * @brief Same as ff_subtitles_read_text_chunk(), but read from an AVIOContext.
170  */
171 void ff_subtitles_read_chunk(AVIOContext *pb, AVBPrint *buf);
172 
173 /**
174  * @brief Read a subtitles chunk from FFTextReader.
175  *
176  * A chunk is defined by a multiline "event", ending with a second line break.
177  * The trailing line breaks are trimmed. CRLF are supported.
178  * Example: "foo\r\nbar\r\n\r\nnext" will print "foo\r\nbar" into buf, and pb
179  * will focus on the 'n' of the "next" string.
180  *
181  * @param tr I/O context
182  * @param buf an initialized buf where the chunk is written
183  *
184  * @note buf is cleared before writing into it.
185  */
186 void ff_subtitles_read_text_chunk(FFTextReader *tr, AVBPrint *buf);
187 
188 /**
189  * Get the number of characters to increment to jump to the next line, or to
190  * the end of the string.
191  * The function handles the following line breaks schemes:
192  * LF, CRLF (MS), or standalone CR (old MacOS).
193  */
194 static av_always_inline int ff_subtitles_next_line(const char *ptr)
195 {
196  int n = strcspn(ptr, "\r\n");
197  ptr += n;
198  while (*ptr == '\r') {
199  ptr++;
200  n++;
201  }
202  if (*ptr == '\n')
203  n++;
204  return n;
205 }
206 
207 /**
208  * Read a line of text. Discards line ending characters.
209  * The function handles the following line breaks schemes:
210  * LF, CRLF (MS), or standalone CR (old MacOS).
211  *
212  * Returns the number of bytes written to buf. Always writes a terminating 0,
213  * similar as with snprintf.
214  *
215  * @note returns a negative error code if a \0 byte is found
216  */
217 ptrdiff_t ff_subtitles_read_line(FFTextReader *tr, char *buf, size_t size);
218 
219 #endif /* AVFORMAT_SUBTITLES_H */
r
const char * r
Definition: vf_curves.c:116
FFTextReader::buf_pos
int buf_pos
Definition: subtitles.h:44
ff_utf_type
ff_utf_type
Definition: subtitles.h:34
FFDemuxSubtitlesQueue::nb_subs
int nb_subs
number of subtitles packets
Definition: subtitles.h:104
FFTextReader::type
int type
Definition: subtitles.h:41
ff_text_pos
int64_t ff_text_pos(FFTextReader *r)
Return the byte position of the next byte returned by ff_text_r8().
Definition: subtitles.c:59
merge
static void merge(GetBitContext *gb, uint8_t *dst, uint8_t *src, int size)
Merge two consequent lists of equal size depending on bits read.
Definition: bink.c:220
ff_subtitles_read_seek
int ff_subtitles_read_seek(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags)
Definition: subtitles.c:322
FFDemuxSubtitlesQueue::keep_duplicates
int keep_duplicates
set to 1 to keep duplicated subtitle events
Definition: subtitles.h:108
FF_UTF16LE
@ FF_UTF16LE
Definition: subtitles.h:36
FFTextReader
Definition: subtitles.h:40
ff_subtitles_read_chunk
void ff_subtitles_read_chunk(AVIOContext *pb, AVBPrint *buf)
Same as ff_subtitles_read_text_chunk(), but read from an AVIOContext.
Definition: subtitles.c:427
ff_subtitles_queue_finalize
void ff_subtitles_queue_finalize(void *log_ctx, FFDemuxSubtitlesQueue *q)
Set missing durations, sort subtitles by PTS (and then byte position), and drop duplicated events.
Definition: subtitles.c:197
ff_text_peek_r8
int ff_text_peek_r8(FFTextReader *r)
Like ff_text_r8(), but don't remove the byte from the buffer.
Definition: subtitles.c:96
FFDemuxSubtitlesQueue::current_sub_idx
int current_sub_idx
current position for the read packet callback
Definition: subtitles.h:106
ff_text_r8
int ff_text_r8(FFTextReader *r)
Return the next byte.
Definition: subtitles.c:64
ff_smil_extract_next_text_chunk
int ff_smil_extract_next_text_chunk(FFTextReader *tr, AVBPrint *buf, char *c)
SMIL helper to load next chunk ("<...>" or untagged content) in buf.
Definition: subtitles.c:337
ff_subtitles_queue_insert
AVPacket * ff_subtitles_queue_insert(FFDemuxSubtitlesQueue *q, const uint8_t *event, size_t len, int merge)
Insert a new subtitle event.
Definition: subtitles.c:110
ff_text_eof
int ff_text_eof(FFTextReader *r)
Return non-zero if EOF was reached.
Definition: subtitles.c:91
pkt
AVPacket * pkt
Definition: movenc.c:59
s
#define s(width, name)
Definition: cbs_vp9.c:257
ff_subtitles_queue_clean
void ff_subtitles_queue_clean(FFDemuxSubtitlesQueue *q)
Remove and destroy all the subtitles packets.
Definition: subtitles.c:306
FFTextReader::pb
AVIOContext * pb
Definition: subtitles.h:42
SUB_SORT_POS_TS
@ SUB_SORT_POS_TS
sort by position, then timestamps
Definition: subtitles.h:31
AVFormatContext
Format I/O context.
Definition: avformat.h:1107
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
ff_subtitles_read_packet
int ff_subtitles_read_packet(AVFormatContext *s, AVPacket *pkt)
Definition: subtitles.c:316
AVIOContext
Bytestream IO Context.
Definition: avio.h:161
ff_subtitles_read_text_chunk
void ff_subtitles_read_text_chunk(FFTextReader *tr, AVBPrint *buf)
Read a subtitles chunk from FFTextReader.
Definition: subtitles.c:385
ff_smil_get_attr_ptr
const char * ff_smil_get_attr_ptr(const char *s, const char *attr)
SMIL helper to point on the value of an attribute in the given tag.
Definition: subtitles.c:360
size
int size
Definition: twinvq_data.h:10344
ff_subtitles_read_close
int ff_subtitles_read_close(AVFormatContext *s)
Definition: subtitles.c:330
FFDemuxSubtitlesQueue
Definition: subtitles.h:102
FF_UTF16BE
@ FF_UTF16BE
Definition: subtitles.h:37
ff_text_read
void ff_text_read(FFTextReader *r, char *buf, size_t size)
Read the given number of bytes (in UTF-8).
Definition: subtitles.c:85
bprint.h
FFDemuxSubtitlesQueue::subs
AVPacket ** subs
array of subtitles packets
Definition: subtitles.h:103
SUB_SORT_TS_POS
@ SUB_SORT_TS_POS
sort by timestamps, then position
Definition: subtitles.h:30
av_always_inline
#define av_always_inline
Definition: attributes.h:49
len
int len
Definition: vorbis_enc_data.h:426
ff_subtitles_read_line
ptrdiff_t ff_subtitles_read_line(FFTextReader *tr, char *buf, size_t size)
Read a line of text.
Definition: subtitles.c:436
avformat.h
ff_subtitles_queue_read_packet
int ff_subtitles_queue_read_packet(FFDemuxSubtitlesQueue *q, AVPacket *pkt)
Generic read_packet() callback for subtitles demuxers using this queue system.
Definition: subtitles.c:215
FF_UTF_8
@ FF_UTF_8
Definition: subtitles.h:35
FFTextReader::buf_pb
AVIOContext buf_pb
Definition: subtitles.h:45
AVPacket
This structure stores compressed data.
Definition: packet.h:350
ff_subtitles_queue_seek
int ff_subtitles_queue_seek(FFDemuxSubtitlesQueue *q, AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags)
Update current_sub_idx to emulate a seek.
Definition: subtitles.c:254
FFDemuxSubtitlesQueue::allocated_size
int allocated_size
allocated size for subs
Definition: subtitles.h:105
ff_text_init_buf
void ff_text_init_buf(FFTextReader *r, void *buf, size_t size)
Similar to ff_text_init_avio(), but sets it up to read from a bounded buffer.
Definition: subtitles.c:52
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
sub_sort
sub_sort
Definition: subtitles.h:29
ff_subtitles_next_line
static av_always_inline int ff_subtitles_next_line(const char *ptr)
Get the number of characters to increment to jump to the next line, or to the end of the string.
Definition: subtitles.h:194
ff_text_init_avio
void ff_text_init_avio(void *s, FFTextReader *r, AVIOContext *pb)
Initialize the FFTextReader from the given AVIOContext.
Definition: subtitles.c:26