4 This document explains guidelines that should be observed (or ignored with
5 good reason) when writing filters for libavfilter.
7 In this document, the word “frame” indicates either a video frame or a group
8 of audio samples, as stored in an AVFilterBuffer structure.
14 The query_formats method should set, for each input and each output links,
15 the list supported formats.
17 For video links, that means pixel format. For audio links, that means
18 channel layout, and sample format (the sample packing is implied by the
21 The lists are not just lists, they are references to shared objects. When
22 the negotiation mechanism computes the intersection of the formats
23 supported at each ends of a link, all references to both lists are
24 replaced with a reference to the intersection. And when a single format is
25 eventually chosen for a link amongst the remaining list, again, all
26 references to the list are updated.
28 That means that if a filter requires that its input and output have the
29 same format amongst a supported list, all it have to do is use a reference
30 to the same list of formats.
33 Buffer references ownership and permissions
34 ===========================================
42 The purpose of these rules is to ensure that frames flow in the filter
43 graph without getting stuck and accumulating somewhere.
45 Simple filters that output one frame for each input frame should not have
48 start_frame / filter_samples
49 ----------------------------
51 These methods are called when a frame is pushed to the filter's input.
52 They can be called at any time except in a reentrant way.
54 If the input frame is enough to produce output, then the filter should
55 push the output frames on the output link immediately.
57 As an exception to the previous rule, if the input frame is enough to
58 produce several output frames, then the filter needs output only at
59 least one per link. The additional frames can be left buffered in the
60 filter; these buffered frames must be flushed immediately if a new input
63 (Example: framerate-doubling filter: start_frame must (1) flush the
64 second copy of the previous frame, if it is still there, (2) push the
65 first copy of the incoming frame, (3) keep the second copy for later.)
67 If the input frame is not enough to produce output, the filter must not
68 call request_frame to get more. It must just process the frame or queue
69 it. The task of requesting more frames is left to the filter's
70 request_frame method or the application.
72 If a filter has several inputs, the filter must be ready for frames
73 arriving randomly on any input. Therefore, any filter with several input
74 will most likely require some kind of queuing mechanism. It is perfectly
75 acceptable to have a limited queue and to drop frames when the inputs
81 This method is called when a frame is wanted on an output.
83 For an input, it should directly call start_frame or filter_samples on
84 the corresponding output.
86 For a filter, if there are queued frames already ready, one of these
87 frames should be pushed. If not, the filter should request a frame on
88 one of its input, repeatedly until at least one frame has been pushed.
91 if request_frame could produce a frame, it should return 0;
92 if it could not for temporary reasons, it should return AVERROR(EAGAIN);
93 if it could not because there are no more frames, it should return
96 The typical implementation of request_frame for a filter with several
97 inputs will look like that:
103 while (!frame_pushed) {
104 input = input_where_a_frame_is_most_needed();
105 ret = avfilter_request_frame(input);
106 if (ret == AVERROR_EOF) {
107 process_eof_on_input();
108 } else if (ret < 0) {
114 Note that, except for filters that can have queued frames, request_frame
115 does not push frames: it requests them to its input, and as a reaction,
116 the start_frame / filter_samples method will be called and do the work.