README.md
1```
2 ___________ ._________
3 \_ _____/______ ____ |__\ _ \_______
4 | __) \_ __ \_/ __ \| / /_\ \_ __ \
5 | \ | | \/\ ___/| \ \_/ \ | \/
6 \___ / |__| \___ >__|\_____ /__|
7 \/ \/ \/
8
9```
10
11*Minimalistic plugin API for video effects, by the Piksel Developers Union*
12
13Updated info on https://frei0r.dyne.org
14
15[![software by Dyne.org](https://files.dyne.org/software_by_dyne.png)](http://www.dyne.org)
16
17[![Build Status](https://travis-ci.org/dyne/frei0r.svg?branch=master)](https://travis-ci.org/dyne/frei0r)
18
19# What frei0r is
20
21Frei0r is a minimalistic plugin API for video effects.
22
23The main emphasis is on simplicity for an API that will round up the
24most common video effects into simple filters, sources and mixers that
25can be controlled by parameters.
26
27It's our hope that this way these simple effects can be shared between
28many applications, avoiding their reimplementation by different
29projects.
30
31## What frei0r is not
32
33Frei0r is not meant as a competing standard to more ambitious efforts
34that try to satisfy the needs of many different applications and more
35complex effects.
36
37It is not meant as a generic API for all kinds of video applications,
38as it doesn't provides things like an extensive parameter mechanism or
39event handling.
40
41Eventually the frei0r API can be wrapped by higher level APIs
42expanding its functionalities
43(for instance as GStreamer, MLT, FFmpeg and others do).
44
45## Current status
46
47Developers are sporadically contributing and we are happy if more
48people like to get involved, so let us know about your creations! Code
49and patches are well accepted, get in touch with us on the
50mailinglist (see the section Communication below).
51
52
53## History
54
55Frei0r has been around since 2004, born from yearly brainstormings
56held at the Piksel conference with the participation of various free
57and open source video software developers.
58
59It works on all hardware platforms without the need for any particular
60hardware acceleration (GNU/Linux, Apple/OSX and MS/Win) and consists
61of more than 100 plugins. Among the free and open source video
62application supporting frei0r are: KDEnLive, FFmpeg, MLT, PureData,
63Open Movie Editor, DVEdit, Gephex, LiVES, FreeJ, VeeJay, Flowblade, and
64Shotcut among the others.
65
66Wikipedia page about frei0r: http://en.wikipedia.org/wiki/Frei0r
67
68
69[Piksel]: http://www.piksel.no
70[PureData]: http://www.artefacte.org/pd/
71[Open Movie Editor]: http://openmovieeditor.sourceforge.net/
72[DVEdit]: http://www.freenet.org.nz/dvedit
73[Gephex]: http://www.gephex.org/
74[LiVES]: http://lives.sf.net
75[FreeJ]: http://freej.dyne.org
76[MøB]: http://mob.bek.no/
77[VeeJay]: http://veejayhq.net
78[MLT]: http://www.mltframework.org/
79[KDEnLive]: http://www.kdenlive.org/
80[Flowblade]: http://code.google.com/p/flowblade/
81[Shotcut]: https://www.shotcut.org/
82
83
84# Downloads
85
86## Source code
87
88Stable frei0r releases are packaged periodically and distributed on
89
90 https://files.dyne.org/frei0r
91
92Frei0r sourcecode is released under the terms of the GNU General Public License and, eventually other compatible Free Software licenses.
93
94The latest source for frei0r plugins can be attained using git on https://github.com/dyne/frei0r
95
96Make sure to get in touch with our mailinglist if you like to contribute.
97
98## Build dependencies
99
100Frei0r can be built on GNU/Linux, M$/Windows and Apple/OSX platforms, possibly in even more environments like embedded devices.
101
102For details see the [INSTALL](/INSTALL.md) file.
103
104### GNU / Linux
105
106Binary packages are mantained on various distributions, but they may not be completely up to date with latest release.
107
108### Apple / OSX
109
110MacPorts provides packages for OSX:
111[MacPorts]: http://www.macports.org
112 $ sudo port install frei0r-plugins
113
114Pre-compiled binaries are also uploaded on our website.
115
116We encourage Apple/OSX application distributors to compile the plugins
117directly and to include frei0r within their bundle.
118
119
120
121### Microsoft / Windows
122
123Pre-compiled binaries are often provided by third-parties, but they may not to be up to date.
124
125We encourage MS/Win application distributors to compile the plugins directly and to include frei0r within their bundle.
126
127
128# Documentation
129
130
131If you are new to frei0r (but not to programming) the best thing is probably to have a look at the [frei0r header](/include/frei0r.h), which is quite simple and well documented. The [doxyfied documentation](http://frei0r.dyne.org/codedoc/html) is also available for browsing on-line.
132
133
134## C++ Filter example
135
136You could find a tutorial filter [here](https://github.com/dyne/frei0r/tree/master/src/filter/tutorial) in the source code.
137A simple skeleton for a frei0r video filter looks like this:
138
139```c++
140 #include <frei0r.hpp>
141
142 typedef struct {
143 int16_t w, h;
144 uint8_t bpp;
145 uint32_t size;
146 } ScreenGeometry;
147
148 class MyExample: public frei0r::filter {
149 public:
150 MyExample(int wdt, int hgt);
151 ~MyExample();
152 virtual void update();
153 private:
154 ScreenGeometry geo;
155 void _init(int wdt, int hgt);
156 }
157
158 MyExample::MyExample() { /* constructor */ }
159 MyExample::~MyExample() { /* destructor */ }
160
161 void MyExample::_init(int wdt, int hgt) {
162 geo.w = wdt;
163 geo.h = hgt;
164 geo.bpp = 32; // this filter works only in RGBA 32bit
165 geo.size = geo.w*geo.h*(geo.bpp/8); // calculate the size in bytes
166 }
167
168 void MyExample::update() {
169 // we get video input via buffer pointer (void*)in
170 uint32_t *src = (uint32_t*)in;
171 // and we give video output via buffer pointer (void*)out
172 uint32_t *dst = (uint32_t*)out;
173 // this example here does just a copy of input to output
174 memcpy(dst, src, geo.size);
175 }
176
177 frei0r::construct<MyExample>
178 plugin("MyExample", "short and simple description for my example",
179 "Who did it", 1, 0);
180```
181
182
183## Communication
184
185You can get in touch with our developer community, send your new effects and share your intentions with us.
186
187We have a free mailinglist open to [subscription](https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/frei0r) and we provide [public archives](https://lists.dyne.org/lurker/list/frei0r.en.html) of the discussions there that are also searchable and indexed online.
188
189For bug reporting the mailinglist is preferred, but is also possible to use an [issue tracker](https://github.com/dyne/frei0r/issues).
190
191## Acknowledgments
192
193Frei0r is the result of a collective effort in coordination with several software developers meeting to find a common standard for video effect plugins to be used among their applications.
194
195For a full list of contributors and the project history, see the file [AUTHORS](/AUTHORS), the [ChangeLog](/ChangeLog) and the project web page: https://frei0r.dyne.org
196
197
198