#+TITLE: Frei0r - free video plugins
#+AUTHOR: Pikselites
#+EMAIL: frei0r-dev@dyne.org
#+LANGUAGE: en
#+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t
#+OPTIONS: TeX:t LaTeX:t skip:t d:nil tags:not-in-toc
#+INFOJS_OPT: path:org-info.js
#+INFOJS_OPT: toc:nil localtoc:nil view:content sdepth:2 mouse:underline buttons:nil
#+INFOJS_OPT: home:http://frei0r.dyne.org
#+LATEX_CLASS: book-1column
#+LATEX_HEADER: \usepackage[english]{babel}
#+LATEX_HEADER: \usepackage{amsfonts, amsmath, amssymb}
#+LATEX_HEADER: \usepackage{ucs}
#+LATEX_HEADER: \usepackage{listings}
#+LATEX_HEADER: \usepackage[utf8x]{inputenc}
#+LATEX_HEADER: \usepackage[T1]{fontenc}
#+LATEX_HEADER: \usepackage{hyperref}
#+LATEX_HEADER: \usepackage[pdftex]{graphicx}
#+LATEX_HEADER: \usepackage{fullpage}
#+LATEX_HEADER: \usepackage{lmodern}
* Introduction
#+HTML: <div id="logo"><img src="http://www.piksel.no/piksel08/piksel/images/piksel_penquin_transparant.png"></div>
** What Frei0r is
Frei0r is a minimalistic plugin API for video effects.
The main emphasis is on simplicity for an API that will round up the
most common video effects into simple filters, sources and mixers that
can be controlled by parameters.
It's our hope that this way these simple effects can be shared between
many applications, avoiding their reimplementation by different
projects.
** What Frei0r is not
Frei0r is not meant as a competing standard to more ambitious efforts
that try to satisfy the needs of many different applications and more
complex effects.
It is not meant as a generic API for all kinds of video applications,
as it doesn't provides things like an extensive parameter mechanism or
event handling.
Eventually the frei0r API can be wrapped by higher level APIs
expanding its functionalities (for instance as GStreamer, MLT, FFmpeg
and others do).
** Current status
#+BEGIN_HTML:
<table width="90%" align="center" cellpadding="5"><tr><td>
<script type="text/javascript" src="http://www.ohloh.net/p/294225/widgets/project_basic_stats.js"></script>
</td><td>
<script type="text/javascript" src="http://www.ohloh.net/p/294225/widgets/project_languages.js"></script>
</td></tr></table>
#+END_HTML:
If you like to peek in what's boiling in the pot, have a look at our
[[file:TODO][TODO]]
Developers are sporadically contributing and we are happy if more
people like to get involved, so let us know about your creations! Code
and patches are well accepted, get in touch with us on the
mailinglist.
** Code gallery
You might want to look at the code in frei0r more in detail, then
browse the existing effects by visiting the [[/gallery][Frei0r plugin gallery]].
** History
Frei0r has been around since 2006, born from yearly brainstormings
held at the [[http://www.piksel.no][Piksel]] conference with the participation of various free
and open source video software developers.
It is mostly adopted on GNU/Linux and OSX platforms, counts more than
80 effects implemented and is used by free video applications as
[[http://www.artefacte.org/pd/][PureData]], [[http://openmovieeditor.sourceforge.net/][Open Movie Editor]], [[http://www.freenet.org.nz/dvedit][DVEdit]], [[http://www.gephex.org/][Gephex]], [[http://lives.sf.net][LiVES]], [[http://freej.dyne.org][FreeJ]], [[http://mob.bek.no/][MøB]],
[[http://veejayhq.net][VeeJay]], [[http://www.mltframework.org/][MLT]] and [[http://www.kdenlive.org/][KDEnLive]] among the others.
Find our more on the [[http://en.wikipedia.org/wiki/Frei0r][Wikipedia page about Frei0r]].
* Download
** Source code
Stable frei0r releases are packaged periodically and distributed on
ftp://ftp.dyne.org/frei0r
We encourage the unauthorized mirroring of this source repository by
all those interested, using the command
rsync -Pr rsync.dyne.org::frei0r .
Frei0r sourcecode is released under the terms of the GNU General
Public License and, eventually other compatible Free Software
licenses.
The latest source for frei0r plugins can be attained using our
revisioning system *GIT*
: git clone git://code.dyne.org/frei0r.git
Daily snapshots are on the FTP and on [[http://www.piksel.no/frei0r/snapshot/][www.piksel.no/frei0r/snapshot]]
*** Build dependencies
+ GNU autotools ( ./configure && make )
or
+ CMake ( cmake . && make )
Frei0r can be built on GNU/Linux, M$/Windows and Apple/OSX platforms,
possibly in even more environments.
**** Optional Dependencies
+ [[http://gmerlin.sourceforge.net/][Gavl]] ( required for scale0tilt and vectorscope filters )
+ [[http://opencvlibrary.sourceforge.net/][OpenCV]] (required for facebl0r filter )
** Debian / Ubuntu
Binary packages are mantained for Debian ([[http://packages.qa.debian.org/f/frei0r.html][QA]]) and Ubuntu ([[http://packages.ubuntu.com/search?searchon=names&keywords=frei0r][pkg]]), to
install the stable version distributed use *apt-get* or *synaptic*:
: sudo apt-get install frei0r-plugins
** Apple / OSX
[[http://www.macports.org][MacPorts]] provide ready to install packages for OSX: in case you have
this packaging system installed, you just need to open a terminal and
give the following command:
: sudo port install frei0r-plugins
* Documentation
If you are new to frei0r (but not to programming) the best thing is
probably to have a look at the [[/codedoc/html/frei0r_8h-source.html][frei0r header]], which is quite simple
and well documented
** API explanation
While the main source of documentation for the Frei0r API is the
header, the sourcecode is well commented so you can study its full
[[http://frei0r.dyne.org/codedoc/html][doxyfied documentation]] online.
** C++ Filter example
A simple skeleton for a frei0r video filter looks like this:
#+BEGIN_SRC c++
#include <frei0r.hpp>
typedef struct {
int16_t w, h;
uint8_t bpp;
uint32_t size;
} ScreenGeometry;
class MyExample: public frei0r::filter {
public:
MyExample(int wdt, int hgt);
~MyExample();
virtual void update();
private:
ScreenGeometry geo;
void _init(int wdt, int hgt);
}
MyExample::MyExample() { /* constructor */ }
MyExample::~MyExample() { /* destructor */ }
void MyExample::_init(int wdt, int hgt) {
geo.w = wdt;
geo.h = hgt;
geo.bpp = 32; // this filter works only in RGBA 32bit
geo.size = geo.w*geo.h*(geo.bpp/8); // calculate the size in bytes
}
void MyExample::update() {
// we get video input via buffer pointer (void*)in
uint32_t *src = (uint32_t*)in;
// and we give video output via buffer pointer (void*)out
uint32_t *dst = (uint32_t*)out;
// this example here does just a copy of input to output
memcpy(dst, src, geo.size);
}
frei0r::construct<MyExample>
plugin("MyExample", "short and simple description for my example",
"Who did it", 1, 0);
#+END_SRC
* Communication
You can get in touch with our developer community, send your new
effects and share your intentions with us.
We have a free mailinglist open to subscription on [[https://piksel.no/mailman/listinfo/frei0r-devel][frei0r-devel]] with
[[http://piksel.no/pipermail/frei0r-devel/][public archives]] that are also [[http://blog.gmane.org/gmane.comp.video.frei0r.devel][searchable and indexed]] online.
For effective and indexed bug reporting regarding plugin
implementations and platform builds, here is a publicly available
[[http://www.piksel.no/projects/frei0r/report][issue tracker]].
* Acknowledgments
#+HTML: <img src="images/livido_pikselites01.jpg" alt="pikselites pic1" align="left" hspace="5">
Frei0r is the result of a collective effort in coordination with
several software developers meeting at [[http://www.piksel.no][Piksel]] between 2003 and 2005 to
find a common standard for video effect plugins to be used among their
applications: Andraz Tori (Cinelerra/CVS), Daniel Fischer
(Pakt/GStreamet), Denis Jaromil Rojo (FreeJ/Dyne), Gabriel "Salsaman"
Finch (LiVES), Kentaro Fukuchi (EffecTV), Niels Elburg (VeeJay),
Øyvind Kolås (Gegl/Babl/Gimp), Tom Schouten (PDP/PureData), Georg
Seidel, Martin Bayer and Phillip Promesberger (Gephex).
#+HTML: <img src="images/livido_pikselites02.jpg" alt="pikselites pic1" align="right" hspace="5">
We first aimed at the realisation of a comprehensive specification for
dynamically loaded plugins named [[http://livido.dyne.org/codedoc/][LiViDO]], which then spawned two
implementations: one being Frei0r, a minimalistic implementation
contributed by the Gephex team and the other one being the [[http://lives.cvs.sourceforge.net/lives/lives/weed-docs/][WEED]]
implementation by LiVES developer Salsaman, sporting more features for
GUI integration and scriptability.
#+HTML: <img src="images/livido_pikselites03.jpg" alt="pikselites pic1" align="left" hspace="5">
Within the span of a few years, the minimalistic approach of *frei0r*
has been widely adopted among more applications and became a *de-facto
standard*. Maintenance and further refinements were contributed by
Carlo Prelz (MøB/BEK), Richard Spindler (Open Movie Editor) and Dan
Dennedy (MLT/KDEnLive), while Debian/Ubuntu packaging and build system
standardization were taken care of by dyne.org developers Filippo
Giunchedi and Luca Bigliardi. For a complete list of contributors,
please refer to the [[AUTHORS]] file.
---------------------------------------------------------------------