Professional Documents
Culture Documents
http://lives.sourceforge.net
This manual is published under the GNU Free Documentation License: http://www.gnu.org/copyleft/fdl.html
This manual is made available thanks to the generous sponsorship of Jeremiah T. Gray, author of creator of "Hackett and Bankwell," The Linux Comic. http://hackettandbankwell.com/
Table of Contents
0 Foreword 1 Introduction 1.1 Introduction to the LiVES Project and the LiVES application 1.1.1 Translations 1.2 Getting support 1.2.1 Bugs and feature requests 1.2.2 Mailing lists 1.2.3 Forums 1.2.4 IRC 1.2.5 RSS 2.0 news feed 2 Compiling and installation 2.1 Obtaining the sourcecode 2.2 License 2.3 Pre-requisites 2.4 Binary locations 2.5 Compiling from source 2.6 dyne:LiVES CD/pendrive 2.7 Initial Setup (temporary directory, audio player, theme, etc.) 2.8 Multi-head support 3 Running LiVES 3.1 Command line options, and setting the language 3.2 From a menu 4 The clip editor 4.1 Introduction/overview 4.2 Importing and capturing 4.2.1 Importing clips (single and multiple) 4.2.2 Importing images (single and multiple) 4.2.3 Importing audio 4.2.4 Importing parts of clips 4.2.5 Importing from a remote location (URL) 4.2.6 Importing from DVD/VCD 4.2.7 Importing from DV / HDV 4.2.8 Capturing an external window 4.2.9 Backup/restore 4.3 Switching clips 4.4 Show clip info 4.5 Renaming a clip in the menu 4.6 Closing a clip
4.7 Sets 4.7.1 Introduction to Sets 4.7.2 Saving a Set 4.7.3 Reloading a Set, autoreloading 4.7.4 Deleting a Set 4.8 Projects 4.8.1 Exporting a project 4.8.2 Importing a project 4.9 Encoding 4.9.1 Encoding a clip 4.9.2 Encoding a selection 4.9.3 Encoding with/without audio 4.10 Playing clips 4.10.1 Starting and stopping playback 4.10.2 Playing a selection 4.10.3 The playback pointer 4.10.4 The separate window 4.10.5 Full-screen mode 4.10.6 Playback plugins 4.10.7 Loop modes 4.10.8 Fade mode, double size 4.10.9 Mute mode and volume adjustment 4.11 Editing clips 4.11.1 Selecting frames 4.11.2 Copy 4.11.3 The clipboard 4.11.4 Cut 4.11.5 Paste 4.11.6 Insert 4.11.7 Delete 4.11.8 Decoupling video and audio 4.11.9 Select last insertion 4.11.10 Saving single frames 4.11.11 Undo/redo 4.12 Rendered Effects 4.12.1 Effects 4.12.2 Merging between clips 4.12.3 Select last effect/merge 4.12.4 Locking the selection width 4.12.5 Rendered generators 4.12.6 Installing custom effects, tools and utilities 5 Tools 5.1 Resizing
5.2 Rotating 5.3 Trimming and adding a border 5.4 Resampling 5.5 Changing the playback speed 5.6 Reverse clipboard 6 Audio in clips 6.1 Deleting audio 6.2 Opening new audio 6.3 Appending audio 6.4 Trimming/padding audio 6.5 Inserting silence 6.6 Exporting audio 6.7 Fade in/fade out 6.8 Recording audio for part of a clip or whole clip 6.9 Resampling audio 7 Real-time effects 7.1 Mapping of keys, enabling, disabling 7.2 Keyboard grab/effect mode 7.3 Effects, transitions and generators 7.4 Applying to clips 7.5 Setting parameters, setting defaults, saving defaults 8 Other VJ keys 8.1 Scratching, freezing, reversing, adjusting frame-rate, switching clips, swap fg-bg, nervous 8.2 The k, m, t and tab keys 8.3 Bookmarking clips 9 Recording 9.1 Recording, previewing and rendering 10 Miscellaneous functions 10.1 Crash Protection 10.2 Clearing disk space 10.3 Setting the theme 10.4 Resetting playback speeds and positions 10.5 MIDI/joystick learner 10.6 MIDI synch 10.7 Jack transport synch 11 The multitrack editor 11.1 Setting multitrack details 11.2 The multitrack screen layout 11.3 Inserting video and audio 11.4 Playback in the multitrack editor 11.5 Adding tracks 11.6 Selecting and trimming audio and video blocks 11.7 Splitting and deleting blocks 11.8 Mouse mode, snap mode and audio insert mode
11.9 Moving blocks 11.10 Regions 11.11 Inserting and removing gaps 11.12 Applying effects to blocks and regions 11.13 Audio effects 11.14 Video transitions 11.15 Audio only transitions 11.16 Compositor(s) 11.17 Listing, deleting, editing effects 11.18 Filter maps 11.19 Audio channel controls 11.20 Marking the timeline 11.21 Saving, loading and deleting layouts 11.22 Rendering 11.23 Leaving multitrack mode 11.24 Layout warnings 11.25 Return to Sets and project save/load (layouts) 11.26 View event list 12 Advanced features - streaming 12.1 LiVES to LiVES streaming 12.2 yuv4mpeg streaming 13 Advanced features - remote control/monitoring 13.1 OSC control 13.2 Status socket 13.3 Notify socket 14 Advanced features - batch processing 15 Advanced features - RFX builder tool 16 Preferences 17 Appendices 17.1 HOWTOs 17.2 Troubleshooting 17.3 Technical documentation 17.3.1 Weed specifications 17.3.2 RFX spec 17.3.2.1 LiVES-perl reference 17.3.3 Plugin formats 17.3.3.1 Encoder plugins 17.3.3.2 Real-time effect plugins 17.3.3.3 Video playback plugins 17.3.3.4 Decoder plugins
17.3.4 List of OSC commands 17.3.5 List of OSC notify events 17.3.6 LiVES clip format 17.3.7 LiVES backup format 17.3.8 LiVES Set and project format 17.4 Remote scripting examples 18 Toys 18.1 Mad frames
0 Foreword
* Dharma youth *
"The
only people for me are the mad ones, the ones who are mad to live, mad to talk, mad to be saved, desirous of everything at the same time, the ones who never yawn or say a commonplace thing, but burn, burn, burn, like fabulous yellow Roman candles exploding like spiders across the stars."
- Jack Kerouac, Dharma Bums First let's declare who we are: after 8 years we are able to trace a common denominator among the people active in our network, interconnected by a nomadic approach to development and life. We are young dreamers, as we often like to stir limitations and invent different models to learn, communicate, share and live than those proposed by the societies where we are caged. We have in common that we survived out of the commonplaces, we cultivated our thoughts and sharing methods, knowledge and tools, keeping them out of any box. This is the time in our history in which we'll speak with young voices, when we are moving some crucial steps on which we'll base our architectures, hopefully mixing the inner with the outer, the Ying with the Yang. Some of us are nomads, some settle in different places time to time, some live in the same marginal neighbourhoods of the world where they were born, some are working for multinational IT companies, some are riding bicycles all around the world, some are lecturing in schools, some are exhibiting in art galleries and some are squatting houses. And yes, probably you are one of those, or you have been in contact with us, at least once. What we are proposing here is a new model and we finally acquired a practical vision to develop it in harmony with our different environments. Please continue reading if you like to discover why and how.
* Freedom of Creativity *
"The
growth of the network rendered the nonpropertarian alternative even more practical. What scholarly and popular writing alike denominate as a thing ("the Internet") is actually the name of a social condition: the fact that everyone in the network society is connected directly, without intermediation, to everyone else. The global interconnection of networks eliminated the bottleneck that had required a centralized software manufacturer to rationalize and distribute the outcome of individual innovation in the era of the mainframe."
- Eben Moglen Free and open source software (often referred as FOSS) is, when referring to the original principles endorsed by the Free Software Foundation[1] (FSF), a new model for distribution, development and marketing of immaterial goods. While recommending you to have a look at the philosophy pages published by the FSF, we'll highlight some implications which are most important for us by making our activities possible and motivating them. FOSS implies an economic model based on collaboration instead of competition, fitting in the fields of academic research where sharing of knowledge is fundamental , and development where the joint efforts of different developers can be better sustained when distributed across various nodes. In this regard we like to quote John Nash (Mathematics Nobel in 1994) saying that "the best result will come from everybody in the group doing what's best for himself, and the group". Imagine then that all creations re-produced in this way can also be sold freely by anyone in each context: this opens up an horizon of new business models that are local, avoiding globalized exploitation, still sharing a global pool of knowledge useful to everyone. Furthermore, in the fields of education we believe that the inherent independence of FOSS from commercial influences is crucial in order to empower students with a knowledge that they really own, not making them dependent from merchants owning their creations by imposing licenses on the tools they've learned. And lastly just consider, and feel free to invent more on these tracks, the impact of FOSS in fields such as communication, social networking, games, media and... evolution.
[1] see http://www.fsf.org
* No nationhood *
"Per
far che i secoli tacciano di quel Trattato[2] che traffic la mia patria, insospett le nazioni e scem dignit al tuo nome."
- A Bonaparte liberatore, Ugo Foscolo, 1778-1827 "One Planet, - Public Enemy
One Nation"
Our homelands are displaced and sometimes very different, difficult to be put in contact with the boundaries given by nations. In fact we think that nation states should come to an end, for the borders they impose aren't matching with our aspirations and current ability to relate with each other. During the few years of our lives we have been taught to interact and describe ourselves within national schemes, but the only real boundaries were the differences between our languages, while we have learned to cross them. From our national histories we mostly inherited fears and anger, but with this network we have learned how to bury them, as they don't belong to us anymore. What's left is a just a problem that can be solved: we will stop representing us as part of different nations. Even if we could, we don't intend to build our own nation, nor to propose to you a new social contract, but to cross all of these borders as a unique networked planet, to start a new cartography. We have a planet! and it is young enough to heal the scars left by the last centuries of war, imperialism, colonisation and prevarication that left most people around us cultivating differences and fake identities represented by flags and nationalist propaganda. We aren't claiming to open the borders to the speculation of multinationals, since we are well aware this can be a rhetoric used by neo-liberalist interests to tramp over the autonomy of developing countries. The Contextual integrity[3] of different social ecosystems needs to be respected, but still as of today the national borders haven't succeeded in preserving it. With some exceptions, most of the national programs and cultural funds we agreed to work with were intending each of us would dress a flag, as we were recruited in a decadent game of national pride and competition, with an agenda of cultural, economical and physical domination, tracing all our movements, assimilating them to leviathans that are playing their last violent moves in a chess game for which we are just seamless pieces. This doesn't make sense anymore to our generation, we refuse to identify with the governments holding our passports, while we look forward to relating with each other on the basis of dialogue and exchange, approaches and architectures that can be imagined globally and developed locally, in an open way the channels that let us speak to you right now.
Therefore we declare **the end of nations**, as our generation is connected by a way more complicated intersection of wills, destinies and, most importantly, problems to be solved.
[2] Trattato di Campoformio [3] see Nissenbaum, H, (2007) Contextual Integrity http://crypto.stanford.edu/portia/papers/RevnissenbaumDTP31.pdf
* Networked cities *
"Creo
evolve in a common practice of displacement and re-conjunction, joining the loose ends of our future. Our plan is simple and our project is already in motion. In fact, if you look around yourself, you will already find *us* close. While the current economical and political systems face the difficulty of hiding their own incoherence, we are able to implement their principles better and, most importantly, we are elaborating new ones. We are reclaiming the infrastructure, the liberty to adapt them to our needs, our right to property without strings attached, the freedom to confront ideas without any manipulative mediation, peer to peer, face to face, city to city, human to human. The possibility to grow local communities and economies, eliminating globalised monopolies and living up from our own creations, is there. We are filling the empty spaces left in our own cities, we are setting our own desires and we are collectively able to satisfy them. Furthermore, some of us are seeking contacts with the lower strata of societies, to share a growing autonomy: as much they are excluded by the society they serve, that much they are close to freedom, while it is clear that autonomy is the solution to present crisis. These marginal communities were the villagers who, mostly because of rural poverty, could no longer survive on agriculture, as well as the migrants and refugees who had to escape their birth places, or never had a homeland. They came to the city and they found neither work nor shelter. They created their own jobs out of the cynical logics of capitalism, mostly in refuse recycling. They look ugly to the minorities in power, while most architects and urban planners unjustly call their shelter "illegal settlements". Some of them organise themselves to gain power with solidarity, and those are the squatters. During the past decades we have learnt to enhance our own autonomy in the urban contexts[7], diving across the different contexts composing the cities, disclosing the inner structure of their closed networks, developing a different texture made of relationships that no company can buy. We are the **Weaver Birds**, burung-burung manyar[8], we share our nests in a network, we flow as the river of the spontaneous settlement of Code in Yogyakarta[9], the gypsy neighbourhood of Sulukule in Instanbul, the Chaos Computer Club, all the hacklabs across the world, the self-organised squatters in Amsterdam Berlin Barcelona and more, the hideouts of 2600 and all the other temporary hacker spaces where our future, and your future, is being homebrewed. This document is just the start for a new course, outlining an analysis that is shared among a growing number of young hackers and artists, nourished by their autonomy and knowledge. Our hacker spaces are quickly proliferating as we don't need to build more space rather than penetrate existing empty space, we are highly adaptive and we aim at connecting rather than separating, at being inclusive rather than exclusive, at being effective rather than acquiring status. To those who feel threatened we ask: do not resist us, for we will last longer than you; and leave us space, for you don't
use it while we do. Do it for the good of all of us, because we are your own kids.
[4] Lapassade, G. (1976) Essai sur la transe, ditions universitaires [5] De Jong, A, Schuilenburg, M. (2006) Mediapolis. Popular culture and the city, Rotterdam: 010Publishers [6] Batten, D.F. (1995), Network Cities: Creative Urban Agglomerations for the 21st Century, SAGE [7] Lapassade, G. (1971), L'Autogestion pdagogique, Gauthiers-Villars [8] Burung-Burung Manyar means "Weaver Birds" in bahasa indonesia, is a book by Romo Mengun published in 1992 by Gramedia (Jakarta) [9] the Code riverbank was considered an "illegal settlement" of squatters, while Romo Mengun has been active between 1981 and 1986, gathering the sympathy of intellectuals believing that these poor members of society should be accepted and helped to improve their living conditions. The government of Indonesia planned its forced removal in 1983, but as protests followed the plans were cancelled. Nine years later in 1992 Kampung Code was selected as the winner of the Aga Khan Award for Architecture in the Muslim World. The Code riverside settlement continues to exist until this day, as a remarkable example of urban architecture.
* Horizontal media *
"Whoever
culture."
- Allen Ginsberg, 1926-1997 Our concern about freedom in media is serious, the current urgency justifies all our acts of rebellion, as they become necessary. One of our main activities is patiently weaving the threads for open networks that put us all in contact. But greedy national regimes and criminal organisations threaten us as if they can avoid their fascist nature to be known, while opportunist provokers use our open grounds to have granted the right to offend and generate more wars. About media we certainly accumulated enough knowledge to trace a clear path for our development, as we have been doing since the early days of our existence: we are active in implementing the liberties that the digital age grants us. This intellectual freedom is very important for the development of humanity, for its capacity to analyse its own actions, to weave its faith in harmony. Our plan is to keep on developing more on-site and on-line public space for discussion, following a **decentralised pattern** that grants access to most people on our planet. We created tools for independent media, to multiply the voices in protection of common visions, to avoid that a few media tycoons take over democracies, as is happening in many different places of this world. We are aware of the limits of the present implementation of democracy: while they are busy celebrating their own success over archaic regimes, these systems stopped updating their own architecture and have fallen in control of new enemies which they
cannot even recognise anymore. The solution we propose is simple: maximise the possibilities to recycle existing media infrastructures, open as many channels as possible, free the airwaves, let communication flow in its multiplicity, avoid any mono-directional use of it, give everyone the possibility to run a radio or TV station for it's own digital and physical neighbours, following an organic pattern that will modularise the sharing of sense and let ideas propagate in a horizontal, non hierarchical way. If these media architectures will be linked with education models that foster tolerance we have hope to accelerate the evolution of our planet and grant protection to the minorities that are populating it.
The above copyleft 2008 dyne.org foundation and respective authors. Verbatim copying and distribution is permitted in any medium, provided this notice is preserved. - Read the complete text at http://dyne.org/first_dharma_dyne.pdf
The LiVES Project is very proud to be a part of this movement. Thank you all for your support !
1 Introduction
1.1.1 Translations
Almost everything is in English, but the LIVES application has been translated into other languages too. However, even for those languages that have up to date translations, translation is an ongoing process. If you would like to help with the translation effort, please contact the LiVES team via the mailing lists, or just jump in and get started ! The URL for translators is: https://translations.launchpad.net/lives/trunk
1.2.3 Forums
There are also several discussion forums which can be found at: http://sourceforge.net/forum/?group_id=64341
BSD
Compilation
Development
Irix
Newbie Issues
Open Discussion
OSX / Darwin
Plugins
Video Editing
So if you want to discuss something very specific, here is a space. If you have a question and you want to see if someone already asked it you can look here too.
1.2.4 IRC
LiVES also has its own IRC channel, channel #lives on irc.freenode.net.
In case you want to obtain the latest development code, here is how.
Subversion
As of version 1.0.0, LiVES code was migrated from CVS to Subversion (svn). There are now two branches of LiVES - the stable version, based on LiVES 1.0.0 with bugfixes, and the development version with the same bugfixes, plus new features added since 1.0.0.
Development version
The development version is the "bleeding edge" for those who like to LiVE dangerously. The development version can be viewed/downloaded from Sourceforge. These builds may or may not run or even compile, and if they do they may hang your X server or even worse... mostly it's OK though.
Stable branch
The stable branch is based on the LiVES 1.0.0 code, with any relevant bugfixes backported. It may lack the latest features, but is guaranteed to contain fewer bugs than the development version. The stable version can be viewed/downloaded from Sourceforge.
Development:
svn checkout http://lives.svn.sourceforge.net/svnroot/lives/trunk/ [dir]
Stable:
svn checkout http://lives.svn.sourceforge.net/svnroot/lives/branches/1.0.0/ [dir] Replace [dir] here and below with the directory where you would like to download the code to (e.g. lives or lives-stable).
Older code
Pre 1.0.0 versions of LiVES can be viewed/downloaded from the CVS repository on Sourceforge. This repository was frozen shortly after the 1.0.0 release.
2.2 License
The LIVES application is licensed under the GPL (version 3 or higher). Some of its libraries are licensed under the LGPL (version 3 or higher), where this is the case, it is clearly marked in the sourcecode. It is optionally linked against libOSC which is licensed under a BSD license. This means that you are free to study the code, make any changes you desire, and redistribute the code with your changes, provided you redistribute the source code as well with the same license, and of course credit the original authors !
Read the full license terms here: The GNU GPL: http://www.gnu.org/copyleft/gpl.html The GNU LGPL: http://www.gnu.org/copyleft/lesser.html
2.3 Pre-requisites
- 800 MHz CPU (32 or 64 bit) X86, AMD, or PPC - 256 MB of memory and will need a minimum of about: - 5 GB of disk, (not for the program, but for video clips that you will open).
operating systems: - GNU / Linux or BSD 2.x. The program has also been compiled for Irix, and for OSX / Darwin.
For compilation from source, you will need at least: * GNU automake 1.7 or higher * GNU autoconf 2.57 or higher * GNU gettext 0.12.1 or higher * GNU libtool 1.5.22 or higher * libgtk2.0-dev 2.10 or higher
and to run LiVES successfully: * mplayer 0.90rc1+ compiled with jpeg/png support (version 1.0pre8+ recommended) * ImageMagick 5+ * perl 5+ * gtk+ 2.10+ * libjpeg62 * gdk-pixbuf-loaders * sox with libsox-fmt-all * python 2.3.4+ (recommended) * SDL (recommended) * mencoder 1.0-pre5+ (recommended) * libmjpeg-tools (recommended) * libtheora (recommended) * libjack/jackit (recommended) * xmms (optional) * cdda2wav (optional)
For Linux: Debian LiVES is in the official debian repositories, so: aptitude install lives should just work. Alternately you can use a graphical package manager like synaptic to download and install LiVES. Unofficial packages for LiVES can also be found at debian-multimedia.org. Please follow the instructions there, if you want to use their packages.
http://sourceforge.net/project/showfiles.php?group_id=64341
For subversion checkouts, the above is not necessary, just do: cd <dir> (where <dir> is the directory where the code was downloded to.) For subversion checkouts, you will need to run: ./autogen.sh before continuing. Note the "." before the "/" - this is important. If this fails for any reason, try: ./autogen.sh --verbose which should give a clue as to what went wrong.
now type: ./configure check the output of configure very carefully, following any advice it suggests, and
making any adjustments you may wish to - such as installing optional libraries. If you are happy with the output from configure, then compile the source with: make again, check the output for any warnings or errors.
Assuming everything went OK, you can now install the application with: make install (you probably need to do this as root - on some systems you would become root using "su", on other systems you would run sudo make install )
You can then run lives either from a menu, or by typing in a terminal: lives
Tip: The default location for everything is inside /usr; so executables go in /usr/bin, themes and scripts in /usr/share/lives/, and libraries and compiled plugins in /usr/lib. If you want to select an alternate install location, you can do: ./configure --prefix=/usr/local for example, before doing "make" and "make install" as usual. However, if you do relocate, and this is not a fresh install, you will need to edit your .lives file in your home directory and adjust <prefix_dir> and <lib_dir> so that they point to the correct locations for scripts and plugins.
LiVES also supports overriding the default install location using DESTDIR. For example: make DESTDIR=/opt/lives install
./configure --help
The Jack audio player is better, and is more synchronized with video. But sometimes, some machines have problems, depending on the soundcard. For example, some laptops do not run jack well. So if you know this in advance, you can select Sox. If you choose Jack and LiVES fails to startup properly then you should be able to restart LiVES and select Sox as the audio player. The choice of audio player can also be changed later, in Tools -> Preferences,
Here you can also select mplayer as the audio player. This is not recommended, but
At the first startup there are some other preferences which should be reviewed and
set.
The most important are the directories, especially the temporary directory. It has to
for small projects). If you are unsure how to check for diskspace, in a terminal enter: df this will show the free space of each partition.
If you wish, you can also set the other directories here.
If you change the temporary directory and click OK, you will see a warning - verify that no other instances of Lives are open. If you do have other instances of LiVES running, you should close them before proceeding, otherwise you will lose all the data and clips in them. You can then click OK to proceed. LiVES will restart automatically when the temporary directory is changed.
You can do this by going to Tools -> Preferences -> Themes and selecting a new theme. When you change the theme, LiVES needs to be restarted before the changes are visible (see also section 10.3).
Tip: You may wish to return to this setting once you have experimented with separate window and full-screen playback modes.
3 Running LiVES
Another consideration when starting LiVES - you can choose the language of the interface. Usually this is automatic but on some machines you may need to set this manually. You can do this from the commandline like so (this example is for US English): export LANGUAGE = en_US or for ubuntu / debian (this example is for Brazilian Portuguese): export LANG = pt_BR.utf8
You can start LiVES with parameters: lives <video_file> will start up LiVES and force it to start opening <video_file> immediately. lives <video_file> <start_time> will do the same thing, but will start importing <start_time> seconds into the <video_file>, if possible. lives <video_file> <start_time> <frames> will do as above, but will try to import only <frames> frames, starting at <start_time> seconds.
There are also various commandline options you can pass to LiVES: -help : show all commandline options, and exit -version : print the version, copyright and licensing details, and exit -set <setname> : start up lives and autoload set <setname> [see section 4.7.3] -noset : do not load any set on startup -nogui : do not show the gui [experimental] -aplayer <ap> : start with selected audio player. <ap> can be mplayer, sox or jack Note: This sets the audio player permanently. You can change it in preferences. -jackopts <opts> : <opts> is a bitmap of jack startup options [1 = jack transport client, 2 = jack transport master, 4 = start jack transport server, 8 = pause audio when video paused, 16 = start jack audio server] Note: jackopts are temporary, only for this instance. You need to set them in Preferences if you want to make permanent changes.
-norecover : force no-loading of crash recovery [see section 10.1] -recover : force loading of crash recovery (if present)
and if LiVES is compiled with OSC support: -oscstart <port> : start OSC listener on UDP port <port> [see section 13.1] -nooscstart : do not start OSC listener
As of version 1.1.0: -devicemap <mapfile> : load in device mapping file <mapfile> at startup [see section 10.5] Tip: to start up LiVES with sox as the audio player: lives -aplayer sox -jackopts 0 or with jack as the audio player: lives -aplayer jack -jackopts 16
The audio player will be set permanently, but you may need to go into Preferences and manually adjust the jack options. You can also reset the audio player in Preferences.
4.1 Introduction/overview
Lives has two main modes. What you see here is the Clip Editor. LiVES also has a multitrack window, which is covered in section 11.
You can use the clip editor to create the snippets of video and audio you want, and then open the multitrack window to combine these snippets together. Of course, there are many ways of working with LiVES, and you are not forced to any particular workflow. In the clip editor you can open any number of clips you want. Here you can open (import) video clips, parts of video clips, audio clips, single images and multiple images. Each clip can have a maximum of about 2 billion frames. Tip: LiVES stores video clips on the disk in one of two ways. There is Disk Mode - in this mode, each frame is stored as a separate image file (usually jpeg, but png is possible too). The decoding to images is done when the clip is opened. Then there is File Mode - this is used by only a limited number of formats - at the time of writing, only dv and ogg/theora formats are supported in File Mode. In File Mode, frames are left within the original clip until they are changed, at which point the changed frame is decoded to an image. This results in much faster opening times for these files. However, if a file is opened in File Mode, you must not delete the original file, since LiVES references frames inside it. If you alter all of the frames in a clip which is in File Mode (for example by resizing it), then the clip becomes a Disk Mode clip. You can tell if a clip is in Disk Mode or File Mode by looking at its Info [see section 4.4].
Audio is always stored as raw pcm, and (at least in version 1.0.0 of LiVES) is always decoded when the file is opened, whether in Disk Mode or File Mode.
Here you can preview a file - if it is a video file, you can check that it plays back - if it plays back it will be possible to open it. If you try to preview a video or audio file and nothing happens, try to play the same file with mplayer. If mplayer cannot play the file, then either there is a problem with the video or audio file (it may be damaged), or it may be that you are missing a library which is required to play it. The file can be almost any kind of video file, audio file, or almost any kind of image file. You can also open multiple files by holding down shift or ctrl and clicking on the files you want to open. You can choose also whether files to be opened are to be deinterlaced. In some cases this deinterlacing is done automatically.
Tip: deinterlacing is usually only needed for video which originates in a video camera or TV picture. In these kinds of video clips, one can see that only half of the rows are recorded for each frame, and two consecutive frames are merged together. This is done to save space in the recorded media (for example a video tape). This can be most obvious when the subject is moving rapidly, producing an effect known as tearing where horizontal lines of movement can be clearly observed. LiVES will try to remove this undesirable effect, either automatically, or upon request when opening material. When you click on a file to open it, you should shortly see a progress window, informing you of how many frames (approximately) are left to open, and an estimate of the remaining time. There are three buttons on this progress window:
- preview : pressing this button causes LiVES to show a preview of the file whilst it is being opened. During an opening preview you can also apply realtime effects [see section 7]. - enough : pressing this button causes LiVES to stop opening the current file, and keep whatever has been opened so far. If multiple files are being opened, LiVES will continue with the next file. - cancel : causes LiVES to abandon the current clip, and to not open any more of the selected clips (if multiple clips were selected). Tip: Before opening a clip, you can choose to ignore its audio, by unselecting Encode/Load/Backup with sound, in the File menu.
You can preview what will be imported by clicking on the Preview button. If you select a start time beyond the end of the clip, you will see only blank frames in the preview. You may get fewer frames than requested if the end of the video clip is reached.
Tip: Before opening a clip, you can choose to ignore its audio, by unselecting Encode/Load/Backup with sound, in the File menu.
Fig 4.2.5.1 opening a remote URL In the window which appears, you can enter the URL of the file or stream and click OK. If this fails, you can click Cancel and try again, this time selecting "Do not send
bandwidth information". This sometimes helps. Opening of a remote stream requires you to have the correct libraries for mplayer/ffmpeg. Once the stream begins to open, you can click Preview to preview it. To stop import of a stream and keep what has been imported, click on the Enough button. To cancel an import of a stream, click on the Cancel button.
Click on the menu option File -> Import selection from dvd/vcd -> Import selection from dvd
In the window which appears, enter the Title, Chapter and Audio ID required and click OK
In the next window, enter the Start Time and Number of Frames desired, and click OK
The material should be loaded into LiVES. You can also choose for LiVES to deinterlace the material as it is being imported.
Click on the menu option File -> Import selection from dvd/vcd -> Import selection from dvd
In the window which appears, enter the Title required and click OK
In the next window, enter the Start Time and Number of Frames desired, and click OK
The material should be loaded into LiVES. You can also choose for LiVES to deinterlace the material as it is being imported.
You can use these shuttle controls to locate and preview and clips you want to grab from your camera, and then click on the "Record" button to grab a clip. You can also set the location and filename of the clips which you grab. After grabbing the clips, press Close Window.
You can then load in the clips which were grabbed, by going to File -> Open file / directory, and selecting the appropriate clip(s) [see section 4.2.1] Tip: Another way to import dv material, if you want to import a whole tape, is simply to use dvgrab from the commandline. This will split the tape by default into 1GB pieces. Then in LiVES you can go to File -> Open file / directory, and shift-click to select all of the pieces to be loaded in.
Tip: if you want to capture audio as well as video, there is a setting in Preferences -> Recording -> Record audio when capturing an external window. This option will only work if you are currently using jack as your audio player. Once you have set your record preferences, you can click OK, and another window with instructions will appear. This window just contains guidance - click OK, and then select your target window. At this stage you also have a final chance to cancel the operation. If you click OK, then click on a target window to select it. After a brief pause, LiVES will grab the window, and embed it, recording it. You can still interact with the embedded window with mouse clicks - although keyboard keys will not be passed through to it. When you are done recording, either press "q" - stop, or click on the stop button (if visible). Once recording is stopped, LiVES will clean up the recording, filling in any gaps in the recording, and making sure all frames are correctly sized. Finally you should get a new clip containing the recording. In some cases it is not possible for the window manager to grab the external window - in this case you will see an error message informing you that LiVES was unable to grab any frames. Note: after recording, the grabbed window will be released by LiVES - although it will be returned to the window manager, it may no longer be visible in tab lists or pagers. Unfortunately this is beyond the control of LiVES, but is generally little more than an annoyance. Note: grabbing an external window will only work if you have the program xwininfo installed.
4.2.9 Backup/restore
Within LiVES, it is possible to backup and restore single clips, losslessly. This is only recommended if you want to keep a permanent copy of a particular clip, without encoding it. This may not be what you want !
If you want to keep open the current group of clips to continue editing later, you probably want section 4.7 - Sets
If you want to encode a clip to play back in another video player, you probably want section 4.9 - Encoding
If you want to export a set of clips for use in another copy of LiVES, you probably want section 4.8 - Projects
If you are still here, then you can backup a clip simply with the menu option File -> Backup clip as .lv1 Select this option, then enter a filename you wish to use. You can later restore the clip using File -> Restore clip from .lv1, and selecting the back file you wish to restore from. You can backup a clip without audio. This is done by deselecting Encode/Load/Backup with sound, from the File menu, before backing up a clip. Tip: You can also restore from a backup on startup of LiVES, for example by starting LiVES with: lives vidfile.lv1 See section 3.1 for more startup options.
the current clip has a small "X" beside it in the Clips menu.
details of the Current Clip are shown in the LiVES window title.
Tip: Another way to switch clips is with the keyboard, using ctrl-page-up and ctrl-page-down. See also section 8.1
Tip: if a video clip is in File mode [see section 4.1], you will see the number of virtual frames and the number of decoded frames listed in the frames box. Virtual frames are those which are still contained inside the original clip; decoded frames have been copied as images. Once all of the frames have been decoded, the clip will then be in Disk mode, and a complete copy of it will exist in the LiVES temporary directory.
4.7 Sets
Here you will be prompted if you want to keep the existing clip Set and just close it, or whether you want to delete all of the clips (and hence the clip Set too). Select Save, and give the set a name, then click OK. The clips will be closed, but will remain on the disk ready for you to reload.
In this case you will be prompted whether to keep the current clips as a set, or whether to delete them. Click on the option to Save Set, and give the set a name, then click OK. LiVES will exit, but the clip Set will remain on the disk.
In both cases you will get a warning that saving a Set will leave the frames on the hard drive, and that this can use disk space. There is an option to not show this warning any more - if you select this, then the warning may be re-activated in Preferences -> Warnings. When saving a Set, there is also the option given to auto-reload the Set the next time LiVES starts up. This is useful if you are working on the same set over several sessions. Tip: be sure to remember the name of your set as it is not (currently) possible to see a list of saved sets on a disk. If you do forget, you can list the contents of the LiVES temporary directory, which will show you all of the sets you have saved (and more).
If you give the name of a different, already existing Set, LiVES will ask you if you want to merge the current clips with that set. If you click OK, the two sets of clips will be combined into one big Set.
Note: Set names may not be blank, and may not contain spaces.
4.8 Projects
In LiVES, a Project is a Set of clips + various other files associated with that Set (currently this means just the layouts associated with that Set - see section 11.25).
to back up a Set, so that it can be archived and deleted, then retrieved later as necessary
4.9 Encoding
Choose any of the encoders to see what video and audio formats it supports. Some encoders may require additional libraries or programs to operate, and usually you will see a message informing you of this, if you select such an encoder. The multi_encoder is very good. It has many formats. Manuals for some of the encoders are available on the LiVES website. Please refer to these if you want to know more about the requirements of a particular encoder. Tip: LiVES has a choice of over 50 different formats/quality levels for encoding, including Video formats:
h264
xvid
theora
animated gif
3GP Mobile
KVCD an experimental format, but can fit 2 hours of video on a CD, or almost 20 hours of video on a DVD
dirac
mng
Audio formats:
vorbis
pcm
mp3
mpeg2
aac
amr
Container formats:
avi
mpeg
ogg
mkv (matroska)
nut
In the same window, you can choose the frame size (width and height) and frame rate (frames per second). It may not always be possible to encode in certain format at any selected frame size and frame rate. In this case, LiVES will inform you of the problem, and allow you to adjust the values to the nearest allowed values. Occasionally, it will be necessary for LiVES to adjust the audio as well. Any such changes made (resizing, resampling frame rate, and audio changes) can be undone after encoding has completed. This is done through the menu option Edit -> Undo, or using the keys ctrl-u.
Note: a very important option is the Debug Mode option. If you are having problems with a particular encoder/codec combination, then you can enable this option before encoding. If you start LiVES from a terminal window then you will see the output of the encoder in the terminal window. This is very useful when resolving problems. For some advanced encoder / codec combinations you will get an options window, which will allow tweaking of certain values. An example of this is the mjpegtools_encoder / mpeg2 custom format.
After clicking OK, another window appears - this will let you set the name of the author, title and comments. These fields are only used currently in .avi files, in future other containers may support them.
Fig 4.9.1.2 File comments window Click OK once more, and encoding should start. Encoding can take a considerable amount of time, depending on the size (number of frames) of the clip to be encoded. Tip: If the output file is not created, it is recommended that you restart LiVES from a terminal, and enable Debug Mode for the encoder. Then carefully check the output shown in the terminal window. In many cases this will give enough information to be able to resolve any problems Once you have saved a clip using File -> Encode clip as, you can then select File -> Encode clip. This will save the clip again using exactly the same settings as before.
via menu option Play -> Play all (or in the multitrack window, Play -> Play from timeline position), or
by clicking on the Play All button in the separate window [see section 4.10.4]
the end of the video or audio is reached, and loop continuous is not set [see section 4.10.7]
by clicking on the stop button in the separate window [see section 4.10.4]
by clicking on the Play Selection button in the separate window [see section 4.10.4]
Normally this is the first frame in the clip (frame 1), but you can alter this either by clicking on the timeline, or by linking the separate window to the pointer. The pointer can be rewound back to frame 1 by any of the following:
using the Rewind button in the separate window [see section 4.10.4]
If you choose to play selected frames [see section 4.10.2] and the playback pointer is within the selection, playback will start from the pointer and continue to the end of the selection.
Fig 4.10.4.1 the separate window button on the toolbar To deactivate the separate window, you can do any of the following:
The separate window has two modes - sticky mode and non-sticky mode. In sticky mode, the separate window is maintained when nothing is playing. In non-sticky mode, the separate window is destroyed each time playback stops, and is only created again when playback starts. Tip: When not playing, the separate window can be used as an editing tool in the clip editor. It has a frame counter which can be used to freely view frames in the current clip. The frame counter can also be linked to the playback "pointer" [see section 4.10.3] It can also be linked to the start or end frame of the selection [see section 4.11.1]
Go to Tools -> Preferences -> Playback, and pick a playback plugin from the drop-down list.
or, you can set the audio playback plugin at startup time from the commandline, e.g. lives -aplayer jack [see section 3.1]
In Preferences, video playback plugins have an Advanced button, which can be clicked on to set the video playback plugin properties (if any). Some examples of video playback plugins are:
SDL playback plugin : provides faster full-screen playback on many video cards
lives2lives_stream plugin : allows streaming of video from one copy of LiVES to another [see section 12.1]
yuv4mpeg_stream plugin : produces stream output on stdout in yuv4mpeg format [see section 12.2]
Note: video playback plugins are currently only active in full-screen, separate window (fs) mode. When a new video playback plugin is selected, you will see a warning advising you of this.
mplayer: very basic audio player, only retained for backwards compatibility, and for testing
Audio plugins are active in all playback modes. Audio plugins are also used for recording of external audio.
A second loop mode is Continuous loop. This means that video and audio will keep repeating until playback is stopped manually [see section 4.10.1]. If the foreground clip is switched during playback [see section 8.1], LiVES will silently enter this mode.
A third loop mode is ping-pong loop. In this mode, when video reaches the last frame, it will play backwards until the first frame is reached, and then it play forwards again. All of these modes can be selected/deselected from the Play menu. Additionally, the "o" key will select/deselect continuous loop mode (for the sox audio player this key will not work during playback). The "g" key will select/deselect ping-pong loop mode. Continuous loop can also be selected from the toolbar Loop icon, or from the separate window Loop icon (in Clip Editor mode only).
These modes can be combined in any way desired; however, if Continuous looping is enabled, then Loop video to fit audio is redundant. When playing a selection [see section 4.10.2], only the selected audio and video will be looped. However, the selection can be adjusted even during playback [see section 4.11.1].
Tip: The only mode which affects audio by default is Continuous loop mode. However, if the jack audio player is being used, and the Preference "audio follows video rate/direction" is enabled, then the audio will be affected by all loop modes, including ping-pong mode. Note: in Multitrack mode [see section 11.4], only Continuous loop is available.
Tip: in fade mode it can sometimes be visually pleasing to hide the frame counter. The frame counter can be hidden in any of the following ways:
Double size as its name suggests, forces the video playback to be double sized height and width are doubled and the image is magnified. If doubling the video size would make it too large to fit on the screen, then the size may be limited. (In this case it may be better to use full-screen mode [see section 4.10.5]. To enter double size mode:
press the "z" key once during playback (jack audio player only), or
click on the Mute Audio icon in the separate window (clip editor mode only)
press the "z" key once during playback (jack audio player only), or
click on the Mute Audio icon in the separate window (clip editor mode only)
Note: mute mode only affects the audibility of audio. For example if Loop video to fit audio is selected, video will still loop to fit the audio even if the audio is muted.
Note: if you are using jack audio playback, the overall audio volume can be adjusted from the toolbar audio slider.
The selection is used for various editing and effects operations as will be explained below. It is also possible to play back just the selection [see section 4.10.2], and to encode just the selection [see section 4.9.2]. Selections are the basis of almost all operations in the clip editor, so it is important to understand them. There are various ways to create a selection for the current clip. One way is to change the values in the start and end spin buttons. Also:
Left clicking with the mouse in the timeline bars will move whichever end is closest (start or end) to the mouse position.
Right clicking with the mouse on the timeline bars will allow you to draw out a selection.
Middle click on the timeline bars will create a selection of just one frame at the position clicked.
You can also adjust the selection from the menus or using the keyboard:
Edit -> Select -> Select all frames, will select from frame 1 to the last frame in the clip. You can achieve the same result by pressing ctrl-a.
Edit -> Select -> Start frame only, will select just the single start frame of the selection. You can achieve the same result by pressing ctrl-Home.
Edit -> Select -> End frame only, will select just the single end frame of the selection. You can achieve the same result by pressing ctrl-End.
Edit -> Select -> Select from First Frame, will set the start frame to 1.
Edit -> Select -> Select to Last Frame, will set the end frame to the last frame in the clip.
Tip: It is also possible to adjust the selection from within the Separate window. To adjust the start frame, link the frame counter to Start, using the button near the bottom of the window. To adjust the end frame, link the frame counter to End, using the button near the bottom of the window.
4.11.2 Copy
You can copy frames (and possibly audio) from the current selection into the clipboard. This is done with the menu option Edit -> Copy Selection, or by using the keys ctrl-c.
You can view the details of the clipboard contents using the option Info -> Show clipboard info. The information shown is in the same format as a normal clip information [see section 4.4]. The clipboard contents can be played back, either by using the menu option Play -> Play clipboard, or by pressing the "c" key when nothing is playing. Tip: The clipboard video frames can be reversed (so they play backwards) using the menu option Tools -> Reverse Clipboard, or by pressing ctrl-x. This is useful for creating video loops - first copy a clip, then reverse the clipboard, then insert the clipboard contents after the original.
Cut can be undone with the menu option Edit -> Undo Cut. A copy of the frames will remain in the clipboard.
4.11.4 Cut
Cut will delete the selected video (and possibly audio) from the current clip and copy the deleted selection to the clipboard. Cut is achieved using the menu option Edit ->Cut Selection, or with the key combination ctrl-t. Delete can be undone with the menu option Edit -> Undo Cut.
4.11.5 Paste
Paste causes the clipboard contents to be copied to a new clip. The new clip inherits all of the properties of the clipboard, for example frame width and height and frames per second, and audio values (if applicable). The clipboard contents remain unchanged. Paste is achieved using the menu option Edit -> Paste as New, or with the key combination ctrl-n.
4.11.6 Insert
Insert copies the frames (and possibly audio) in the clipboard and inserts them in the current clip. You can select whether to insert before or after the current selection, and the number of times to insert. If the target clip has audio, then the option Insert to Fit Audio can be checked. In this case enough copies of the clipboard will be inserted so that the video continues until the exact end of the audio . You can insert either into the clip which the video was copied from, or any other clip, simply by switching to the other clip [see section 4.3]. In the case that you insert into another clip, the video (and audio) will be resampled or sped up/slowed down to fit into the target clip. In addition the frames will be resized to match the target clip. Tip: you can choose whether inserted video is resampled or sped up/slowed down using the options in Tools -> Preferences -> Misc, When Inserting/Merging Frames. The default is to resample, as this will cause a minimum of visible change in the resulting video. For some purposes, you may wish to select the other option. Audio is always resampled (if necessary).
Insert is achieved using the menu option Edit -> Insert from Clipboard, or with the key combination ctrl-i.
Note: Insert adds new frames to the target clip. If you want to mix the clipboard frames into the target clip, then what you need is Merge [see section 4.12.2]. Insert can be undone with the menu option Edit -> Undo Insert.
4.11.7 Delete
Delete will delete the selected video (and possibly audio) without disturbing the contents of the clipboard. Delete is achieved using the menu option Edit -> Delete Selection, or with the key combination ctrl-d. Delete can be undone with the menu option Edit -> Undo Delete.
Note: since Image Magick is used to convert the image, the image format can be any one supported by Image Magick. See http://www.imagemagick.org/script/formats.php for further information.
4.11.11 Undo/redo
Almost all operations in the Clip Editor can be undone; however there is currently only one level of undo for each clip. To undo an operation:
or press ctrl-u
Operations which can be undone include: cut, delete, insert, merge, apply effects, resize, resample, change speed, resample audio, insert silence, delete audio, fade audio in/out, record new audio, trim frames, rotate clip, load new audio, append audio.
or press ctrl-z
4.12.1 Effects
LiVES has two types of effects, realtime effects and rendered effects. Realtime effects will be discussed in section 7. Here we concern ourselves with rendered effects. While realtime effects are designed for speed, rendered effects may take longer to process, but may produce more interesting or accurate results. Effects (or filters as they are more technically known), can also be divided into several sub-types depending on their function. Generators (or sources) take no video input, they simply produce video (and possibly audio). Transitions merge or overlay two video inputs into one video output. Effects take one input video stream and produce one output. Sometimes when we talk about effects we mean all of these types together.
Frames can be merged between clips or within the same clip. In fact, merging is done
between the current selection and the clipboard, so the frames to be merged first need to be copied or cut. Then the frames which these are to be merged into need to be selected. Once this has been done, the frames from the clipboard and the selection can be merged together. This is done with the menu option Edit -> Merge Clipboard with Selection. There is no keyboard shortcut for this.
Once the menu option is selected, the Merge window will appear.
At the top you will see the Merge details, how many frames from the clipboard will be merged with how many frames in the selection. In many cases, frames in the clipboard will need resampling in order to match the target clip. In this case you will see the number of resampled frames displayed. You can choose whether to align the starts of the clipboard and selection, or whether to align the ends. Aligning the starts means that the first frame of the clipboard will be merged with the first frame of the selection. Aligning the ends means that the last frame of the clipboard will be merged with the last frame of the selection. This makes
a difference if the number of frames differs between the clipboard and the selection,
If the (resampled) clipboard contains more frames than the selection, you will also have two options for how to handle the extra frames:
If the (resampled) clipboard contains fewer frames than the selection, you will be offered the option to loop the clipboard to fit the selection.
Below these options, you can choose the Transition Method. Depending on the Transition Method, there are other options which define how the frames will be merged together.
Once you have set all the options to your satisfaction, click OK to begin the merge. As with effects, you can Preview the merge, and you can also Pause it or Cancel. When Paused you can choose to Preview, Resume, or Keep the frames which have been processed so far. Otherwise, simply wait, and the Merge should take place as requested. The Merge can be undone using the menu option Edit -> Undo Merge.
clicking in the timeline to the left of the selection will cause the selection to move to the previous block of n frames clicking in the timeline to the right of the selection will cause the selection to move to the next block of n frames adjusting the start or end frame value will shift frames left or right, keeping the same selection length
To unlock the selection width, deselect the menu option Edit -> Lock Selection Width.
Tip: Unless specified otherwise, frames will be generated at the default frame rate. The default frame rate can be altered in Preferences -> Misc (default FPS).
for custom generators, in the Tools -> Generate -> Custom Generators menu
for custom transitions, in the Edit -> Merge Clipboard with Selection window, in the Transition Method drop-down list
Tip: there are also Custom Tools and Custom Utilities which can be installed. Custom Tools will appear in the Tools -> Custom Tools menu, and custom Utilities in the Tools -> Utilities -> Custom Utilities menu. Tools are explained below; utilities are small add-ons which do not affect clips at all. It is also possible to create and share your own custom effects, tools and utilities. This is explained in detail in section 15.
Note: you can check your version of LiVES by clicking on Help -> About
5 Tools
In LiVES, Tools are similar to effects in many ways, but whereas an effect or transition will apply only to a selection, Tools are always applied to an entire clip. The Clip Editor has various builtin tools, and it is also possible to install Custom Tools [see section 4.12.6] and to create test tools [see section 15].
5.1 Resizing
The Resize tool can be used to change the frame size. To resize the current clip, click on Tools -> Resize All Frames. Enter the new frame size and click OK. All of the frames in the clip will be resized. Note the Maintain Aspect Ratio check-box which is offered as an option. If this is checked (the default), then LiVES will lock the width and height so as to maintain the Aspect Ratio of the clip. You can uncheck this if you want to set the height and width values independently.
Fig. 5.1.1 the Resize tool During processing, you can Preview the resized frames, you can Pause the processing, or you can Cancel. Once Paused, you can again Preview the processing, Resume resizing, or Cancel. Resize can be undone using the menu option Edit -> Undo Resize all Frames. Tip: the Aspect Ratio of a clip is the ratio of the width of the clip against its height. For example, for a clip with dimensions 640 x 480, the Aspect Ratio is 640 / 480, which is expressed more simply as 4:3. This is the same ratio which is used for television (old style). More modern televisions may use widescreen - an aspect ratio of 16:9. Other common aspect ratios are 1:1 (square), and 1:2.2. Sometimes you may see mention of a frame aspect ratio - this is used for example for letter-boxing, where the frame is a different ratio from the image inside. There is also pixel aspect ratio, which is used to describe the shape of a single pixel (square or rectangular). If you think this is confusing - don't worry - in 99% of cases, LiVES will take care of the Aspect Ratio for you automatically.
5.2 Rotating
Another tool available for use in the Clip Editor is the Rotate tool. This tool can be used to rotate all video frames in the current clip by a constant amount. To rotate the current clip, click on Tools -> Rotate Clip. Enter the number of degrees to rotate the frames by and click OK. All of the frames in the clip will be rotated by the chosen amount. Note that rotating the clip may change the size of frames. For example, if a clip with frame size 640 (width) x 480 (height) is rotated by 90, the frames will end up with a new size of 480 (width) x 640 (height). You can also enter a background colour. This is used to fill in any blank space to make the frames rectangular.
Fig. 5.2.1 the Rotate tool During processing, you can Preview the rotated frames, you can Pause the processing, or you can Cancel. Once Paused, you can again Preview the processing, Resume rotating, or Cancel. Rotate can be undone using the menu option Edit -> Undo Rotate Clip. Tip: if you want to rotate a clip or part of a clip without changing the frame size, you can use the Spin effect (menu option Effects -> Spin).
A new window will appear which will allow you to enter the desired values for this tool.
The upper part allows selection of the area to be trimmed. You can also use the mouse to select part of the image in the preview area, by clicking and holding. The slider below the preview allows you view various frames in the clip. You can also choose to keep the trim area centred, and there is a button to reset the values to show the full frame again.
Fig. 5.3.1 the Trimming and Bordering tool In the lower part, you can choose to add a border of any colour and size. If you choose to Add Border, and keep the default values,the border will exactly fill the trimmed off area. Otherwise you can choose the border size and the position of the video frame within the border. Once you are happy with all values, click OK. During processing, you can Preview the trimmed frames, you can Pause the processing, or you can Cancel. Once Paused, you can again Preview the processing, Resume trimming, or Cancel. Trimming and bordering can be undone with the menu option Edit -> Undo Trim frames/Add border. Tip: the border settings area has a check button Maintain Aspect Ratio. With this checked, the aspect ratio of the border will be fixed to the aspect ratio of the original frame. If you deselect this check button, then you can freely set the size of the surrounding border.
5.4 Resampling
Resampling means changing the rate (frequency) of something without changing the length (duration). In this case, resampling means changing the number of frames per second without changing the overall length of the video. LiVES does this by either duplicating or removing frames, ideally in such a way that the change is as unnoticeable as possible. For example, I might have a clip with a frame rate of 25 frames per second - if I want to encode this clip to put it on a website, I may want to reduce the number of frames per second in order to make the eventual file size smaller, and thus easier to download or stream. To resample the current clip, click on Tools -> Resample Video to New Frame Rate. Enter the desired new frame rate and click OK.
Fig. 5.4.1 the video Resampling tool During processing you can Cancel if you change your mind. Resampling can be undone using the menu option Edit -> Undo Resample
Note: LiVES itself will automatically resample at times, for example when inserting or merging frames from the clipboard at one frame rate into a video clip with another frame rate.
To change the playback speed of the current clip, click on Tools -> Change Playback/Save Speed. Enter the desired new frame rate and click OK. If you prefer you can enter the duration of the clip in seconds instead - the frame rate will be calculated automatically from this. In addition you can choose whether the audio rate will be changed or not.
During processing you can Cancel if you change your mind. The speed change can be undone using the menu option Edit -> Undo Change Playback/Save Speed Tip: you can combine Resample and Change Speed to duplicate the frames in a clip. Suppose you have a clip composed of 10 single images at 25 frames per second.
Now you want to change this so that each image is held for a duration of 2 seconds. This means you need 50 copies of each image. So what you can do is first change the playback speed to 1 frame per second. Then resample to 50 frames per second. This will cause each frame to be duplicated 50 times. Finally you can change speed back to 25 frames per second again.
Select all frames in a short video clip [see section 4.11.1] Copy the frames to the clipboard [see section 4.11.2] Reverse the clipboard Insert the reversed frames after the original frames [see section 4.11.6]
6 Audio in clips
In this section, we will look at some of the functions for dealing with audio in the Clip Editor.
The audio deletion can be undone using the menu option Edit -> Undo Delete Audio.
The new audio can be undone using the menu option Edit -> Undo Load New Audio.
If you have the tool cdda2wav installed on your machine, you can load a track directly from the CD. First of all you will need to set your CD device in Preferences, (Tools -> Preferences -> Misc); usually this is a device like /dev/cdrom. You can use the browse button next to the entry to look for the device. You can then use the menu option Audio -> Load CD Track. Clicking on this will allow you to select the CD track number. The audio from the CD track will then replace the current audio for the clip.
Fig. 6.5.1 setting values for new audio The operation can be undone using the menu option Edit -> Undo Insert Silence.
Either enter the desired time in seconds (starting from the beginning of clip), or you can choose to fade in over the selection. Click OK, and the audio volume will be smoothly adjusted from zero up to normal volume over the chosen time period. The operation can be undone using the menu option Edit -> Undo Fade Audio In.
Either enter the desired time in seconds (starting from the beginning of clip), or you can choose to fade out over the selection. Click OK, and the audio volume will be smoothly adjusted from normal volume down to zero over the chosen time period. The operation can be undone using the menu option Edit -> Undo Fade Audio Out. These options are only available for clips with audio.
Select the video frames for which you wish to record audio (see section 4.11.1) Activate the menu option Audio Record External Audio to Selection. If the clip has no existing audio you can enter the audio details rate, channels, sample size, signedness, endianness you can select the duration of recording by default this will be the length of the selection. You can adjust this or set it to unlimited. Click OK to record, or Cancel to cancel. Record your audio Either wait for the countdown to expire, or click Enough.
Note: If the selection starts beyond the end of existing audio, silence will be inserted up to the start of the selection. Recording audio can be undone and redone through the menu option Edit Undo/Redo Record New Audio
Activate the menu option Audio Record External Audio to New Clip enter the audio details rate, channels, sample size, signedness, endianness you can select the duration of recording by default this will be the length of the selection. You can adjust this or set it to unlimited. Click OK to record, or Cancel to cancel. Record your audio Either wait for the countdown to expire, or click Enough.
signed/unsigned
Note: that LiVES itself will automatically resample at times, for example when inserting audio from the clipboard into a clip with different audio settings, or occasionally when encoding. The operation can be undone using the menu option Edit -> Undo Resample Audio. This option is only available for clips with audio.
7 Real-time effects
As mentioned in section 4.12, LiVES has two types of effects - the rendered effects and the realtime effects. Here we discuss the realtime effects - these are effects which can be applied during playback, recording, and in the multitrack window.
Fig 7.1.1 Real time effects key values The first thing to note is that the keys and modes are arranged in columns. Each column represents an effect key. The effect keys begin with the combination ctrl-1 on the left, then ctrl-2 next to this, ctrl-3 and so on, normally up to ctrl-9. Tip: Sometimes there can be more than 9 keys, ctrl-10 and upwards are referred to as virtual effect keys. These virtual keys can be controlled from the RTE window, and via external means - OSC, MIDI, or joystick for example. The number of effect keys can be set in Tools -> Preferences -> Effects. The second thing to note is that each effect key has 8 modes. These modes are like a bank of effects for each key - only one mode is active at any one time for each key, this is known as the current mode for that key. The current mode for each key starts at 1, and can be increased if effects are mapped to higher modes of that key. Modes are discussed in more detail in section 7.2.
To map an effect to a key/mode simply click on the drop down list and select the new effect to be mapped. You can even do this while the effect key/mode is active. However, you can only map to a mode higher than 1 if the mode below that also has an effect mapped to it. You can map any type of effect to any valid key/mode - with one restriction, you may not map generators and non-generators [see section 7.3] to the same key. It is also recommended that you map transitions to their own specific key(s), as this makes mode switching easier [see section 7.2].
To un-map an effect, there are two options - either you can click on the button marked Clear All Effects - as its name suggests, this will un-map all effect key/mode combinations, or you can click on the Clear button next to the drop down list. This will clear just the single key/mode, and will cause any higher mode mappings to shift and close the gap. Note: Each key/mode combination also has an Info button. Clicking on this will show some basic information about the mapped effect. If you wish, you can save a new key mapping as the default, by clicking on the Save as default keymap button. The default layout is loaded each time that LiVES starts up. Clicking on the Load default keymap button will cause the current default keymap to be loaded, overwriting any changes which have been made. Tip: LiVES has only one default keymap, however you can switch between keymaps by copying the file ~/.lives-dir/default.keymap to an alternate file and then restoring this at a later time. You can close the RTE window by clicking on the Close window button, or by pressing ctrl-v.
To activate an effect:
press the associated effect key (e.g. ctrl-1, ctrl-2, ctrl-3, etc)
or, in the RTE window, click on the check box labelled "Key active" next to the effect key
or use an external control (for example MIDI keyboard or joystick or OMC) this is explained in the relevant sections
Note: there is no limit to how many realtime effects can be active at any time, other than the number of effect keys. Effects are applied in numerical order of the key they are bound to, i.e. ctrl-1 first, then ctrl-2, ctrl-3, etc. Tip: The exception to the numerical order rule is for generators, which always come first in the order (if there is no transition active), or at the moment of applying each transition (as the second frame source) if there are transitions active. See section 7.3 for more about filter types.
To deactivate an effect:
when the effect is activate, press the associated effect key (e.g. ctrl-1, ctrl-2, ctrl-3, etc)
or, in the RTE window, click on the check box labelled "Key active" next to the effect key to uncheck it
or use an external control (for example MIDI keyboard or joystick or OMC) this is explained in the relevant sections
Note: the key combination ctrl-0 will deactivate all effects. This is very useful to remember. Tip: if you have just a single monitor, and you would like to view playback while the RTE window is open, the best way is to play back in Separate Window mode (see section 4.10.4), and alter the window to make it "Always on top" (how this is done depends on the window manager - generally right clicking on the window title bar will bring up a window manager menu). You can then experiment with the RTE window settings and see the effect in the playback window. If you have two or more monitors, you should be able to open the RTE window in one monitor and the playback window in a second (see section 2.8).
ctrl-up and ctrl-down adjust the first numerical parameter of the effect.
Note: When keyboard grab is off, these keys adjust the playback rate (see section 8.1).
the "m" key cycles through effects bound to the modes of that key the "t" key puts LiVES into text mode. If the effect has a text parameter, all subsequent key-presses will go to the first text parameter of that effect. An example of this is the livetext effect and livetext_generator. To leave text mode, press the Tab key.
press ctrl-0 (all effects off) press ctrl-Backspace (freeze) if the RTE window is open, uncheck the check box marked "Key grab" next to the effect key which has the keyboard grab
Above we saw one way of changing the mode of an effect key - first get keyboard grab (k) and then press "m" to cycle the mode. Other ways of changing the mode are:
with the RTE window open, click on the "Mode active" buttons below each effect key
Fig. 7.3.1 the filter (effect) type is shown in the RTE window By default, LiVES has transitions mapped to modes of key ctrl-8 and various generators mapped to key ctrl-9. If LiVES is not playing and you press the key combination for a generator, this will
initiate playback. A generator is a bit like a clip, because you can apply other effects to it. You can also now apply a transition and mix a generator with a video clip. The only thing with the real time generators - when a generator disappears from view, it closes. For example, start up a generator. Press Ctrl-0 to ensure there are no transitions active. If you now press ctrl-page-up LiVES will switch to another clip, and because the generator is no longer visible, it will close. Some generators also have audio input. If you play audio they will vary their pattern of behaviour in accordance with the movement of the input audio. Examples of these are the libvisual generator plugins (although these are developed independently, and at the time of writing the audio response seemed a bit buggy). If there is one or more realtime transitions active, then the ctrl-page-up and ctrl-pagedown keys will cycle the background clip. Realtime effects triggered from the keyboard are applied only to the foreground clip.
Note: remember that effects can be undone and redone, but there is only one level of undo per clip in the Clip Editor. Note: After applying the effects, remember to switch off the realtime effects (e.g. with ctrl-0), otherwise they will be applied to the selection twice (once to the frames, and then again as realtime effects) !
8 Other VJ keys
Various keys can be used during playback. These keys can be viewed via the menu option VJ - Show VJ Keys. Currently there is no option to remap these keys, although many can be simulated through external controls (OSC, joystick or MIDI controller).
8.1 Scratching, freezing, reversing, adjusting frame-rate, switching clips, swap fg-bg, nervous
ctrl-left and ctrl-right keys can be used to "scratch" with video ctrl-Backspace keys can be used to freeze/unfreeze video (this also releases the keyboard grab - see section 7.2). Audio will continue playing unless the jack audio player is being used, and the preference Audio follows video rate/direction is enabled. ctrl-space keys reverse the playback direction - this also works when video is frozen : when you unfreeze it will play in the reverse direction ctrl-up and ctrl-down keys adjust the frame-rate (unless the keyboard grab is active see section 7.2). ctrl-Enter will return video playback speed to normal. Note: by default the above keys affect only video, however you can get them to adjust audio also. This is done by selecting the jack audio playback method (in Tools -> Preferences -> Playback) and then checking the box Audio follows video rate/direction.
ctrl-page-up and ctrl-page-down keys cycle in both directions through clips - this also works when LiVES is not playing. During playback, these keys will adjust the foreground frame if there are no transitions active, but they alter the background clip if one or more realtime transitions are active. Note: by default the above keys affect only video, however you can get them to adjust audio also. This is done by selecting the jack audio playback method (in Tools -> Preferences -> Playback) and then checking the box Audio follows clip switches.
The "x" key during playback will swap foreground and background clips. This only works if there are one or more realtime transitions active. You may wish to do this sometimes since realtime effects are only applied to the foreground clip. The "n" key during playback toggles Nervous mode. In Nervous mode, the frame to be played back will jump around a little.
9 Recording
You can select whether the following types of event are recorded:
real time effects (including parameter changes) clip switches audio events (provided you are using the jack audio player)
Whether or not to record these events can be set in Tools -> Preferences -> Recording. When LiVES is recording you will see "rec" appear before the frame count in the frame counter.
Once playback finishes, if anything was recorded, a window will pop up asking you what you want to do with the events that were recorded.
Preview the recording Render the recording to the same clip (this is only available if the foreground clip was not switched during playback) Render the recording to a new clip Edit the events in the multitrack window (this is covered in section 11). View the events in the event window (see section 11.26).
Should you choose to render the events to a new clip, you will be presented with another window, where you can enter the details of the new clip. Here you can choose the frame size (width and height in pixels), the frame rate (frames per second) and the audio details. At this point you can optionally select a target encoder for the clip. If you choose to do this, LiVES may suggest more optimal values for the frame size, frame rate and audio values. It is up to you if wish to accept the suggested values or continue with the values as entered. Note that selecting an
encoder here is just for optimisation purposes; you are still free to choose any encoder/format you like when encoding the clip.
Fig. 9.1.2 new clip details Tip: If you want to always render using the same values, you can set this up in Preferences. Use the menu option Tools -> Preferences, and navigate to the Multitrack/Render tab. Check the box marked Use these same values for rendering a clip. Here you can enter the values to be used every time you render a new clip. (Note that these values are shared with the Multitrack Mode values [see section 11.1].)
During rendering you can Preview what is being rendered, Pause the rendering, or Cancel. If you Pause, you can again Preview, Resume rendering or Keep what has been rendered so far.
Note: If you render to the same clip, it is possible to undo this afterwards with the menu option Undo -> Undo Rendering Tip: recording like this is great for creating a clip to go along with some music. First load in a few short clips to play with, then load in the audio as the audio to one of the clips. Hit record "r" and start playing back from this clip. Switch clips and apply effects and so on until the music ends. Then render it all to a new clip. Again, load in the music to the new clip (in case the audio was not rendered) and presto - you have a video clip to go with that music.
Note: LiVES uses two record modes - physical and logical. Logical mode simply makes a note of which frames from which clips are playing, which effects are active, and so on. Physical mode makes a physical copy of the output frame on the disk. Currently LiVES uses logical mode unless there is one or more generators or incoming streams active, in which case it will switch to physical mode. Each mode has its advantages and disadvantages, physical mode can slow disk access and cannot be edited after the fact, logical mode uses no disk access, and can be easily edited afterwards, but what is rendered may not match exactly with what was recorded. You should be aware of these different modes but in general you do not need to worry about them.
10 Miscellaneous functions
Fig. 10.5.1 qjackctl, vkeybd and the LiVES MIDI / joystick learner. Parameter linkage is highlighted in red.
Variables in the input are automatically linked to parameters in the macro, starting from highest index value. The linkage can be seen by opening the parameters tab here you can also set the value of any fixed parameters, simply by clicking on them. You can add an offset and a scale value to the variables (for example if MIDI note begins at 50, you could make an offset of -49 to make the result start at 1). There is also a small check-box next to each variable in the input - checking this makes the variable filter for that value. For example, suppose a button press produces 2 values - 128 (press) and 0 (release).
If you want only the 128 (press) to toggle some value, you can open the variables tab, then click the little check-box next to 128. This value then becomes a filter for the action, rather than a variable (as would happen by default). External control is only active during playback, so you need to start playback manually. You can also save and load device configuration files.
To save a device configuration file, click on VJ -> MIDI/joystick interface -> Save device mapping, and then enter the name of a file to save the device mapping to. To load a device configuration file, click on VJ -> MIDI/joystick interface -> Load device mapping, and select a device map file to load.
As of LiVES version 1.1.0, you can load in a device configuration file at startup, using the startup option: -devicemap <mapfile> See section 3.1 for more details of startup options. Currently supported are:
joystick buttons
MIDI note on
MIDI controller
the joystick/MIDI learner feature is very new, and the following should be noted:
Tip: there is a tab in Tools -> Preferences -> MIDI/joystick learner, which lets you alter and tweak values. Here you can decide which types of peripherals LiVES will listen for : MIDI, joystick, none or both. You can also set the path to each device, although these should be autodetected. Finally, you can also set the MIDI check rate, and the MIDI repeat rate. These values can be adjusted if you are having problems with your MIDI controller. As of LiVES 1.1.0, ALSA MIDI is supported, provided LiVES was compiled with ALSA support, and this is recommended if available (see below). Note: these features are only available if LiVES was compiled with OSC support enabled. Note: as of LiVES 1.1.0, ALSA MIDI support is available if LiVES was compiled with ALSA support. When you load a device map, or enter into the MIDI/joystick learner, LiVES will create a MIDI input port, and you can connect to this using standard MIDI tools (like qjackcontrol or aconnect). ALSA MIDI support is recommended if available, however there is a preference to disable it and use the older method of reading directly from the MIDI device if preferred.
with one or more clips loaded, use the menu entry Edit -> MULTITRACK mode
with one or more clips loaded, press the key combination ctrl-m
after recording (see section 9), select the option to edit the recording in the Multitrack Editor
Unlike the Clip Editor, the Multitrack Editor has multiple levels of undo and redo.
In Multitrack Mode, you will work with a single frame rate, frame size, and one set of audio settings. When entering the Multitrack Editor, LiVES needs to know what these values are. If you wish you can enter these values in Preferences, and LiVES will use your selected values each time. To do this, use the menu option Tools -> Preferences, and navigate to the Multitrack/Render tab. Here you can choose either Prompt me for width, height, fps and audio settings or Always use the following values. If it is set to the latter, LiVES will use the values you have specified when entering Multitrack Mode. Otherwise, you will see a window prompting you to enter these values each time you enter Multitrack Mode. Note: if you plan to restore a layout (or autorestore is on) then the values you enter here may be overridden by stored values in the layout (see section 11.21).
Here you can choose the frame size (width and height in pixels), the frame rate (frames per second) and the audio details. At this point you can optionally select a target encoder for the clip. If you choose to do this, LiVES may suggest more optimal values for the frame size, frame rate and audio values. It is up to you if wish to accept the suggested values or continue with the values as entered. Note that selecting an encoder here is just for optimisation purposes; you are still free to choose any encoder/format you like when encoding the clip.
You can also choose the audio setup which you would like to use. You can have a backing audio track, and/or an audio track per video track. The backing audio track can be used for example for music which will continue throughout the whole timeline. Audio track per video track can be selected to allow each video track to have its own audio. Note: realtime audio playback will only be available if you are using the jack audio player.
as shown here:
The polymorph window, as its name suggests, changes depending on what you are doing. Its modes include: - clip mode (as seen above) : shows all clips loaded in LiVES, and allows them to be dragged onto the timeline. You can enter this mode any time by pressing 'c' (or from the View menu; View -> Clips) - in/out mode : if you double click on a block, the polymorph window will go into in/out mode. You can adjust the start and end points of a block using the in/out spinbuttons. If a block is selected (by double clicking on it) then you can enter this mode by pressing 'i' (or from the View menu; View -> Block In/Out points)
- effect mode : if the last action was to apply an effect, and that effect has parameters, then the polymorph window will go into effect mode. In this mode, you can set effect parameters and preview frames. Frame previews are shown in the preview window. You can return to this mode by editing an effect. - effect list mode : lists the stack of effects (if any) for the current track at the current timeline position. You can get to this mode either by pressing the 'e' key, right clicking on a frame in the timeline and selecting List effects here, or by the menu entry View > Effects at current.
The context window shows information relevant to the current action. This window is only visible in Compact View.
The timeline area contains the timeline header, which is a horizontal ruler marked in seconds. It has a cursor which scrolls during playback, or can be set by clicking in the timeline header. If you click and drag here, you can set a time region (see section 11.10). It also contains the track area. Here you can see your video tracks and audio tracks. Each track has a check-box for "selected/unselected", then a name and a layer number, then a blank area which can be filled with video and audio. Selected/unselected is used for setting the track part of a region (see section 11.10). Layers go from layer 0 at the top, (the "front") downwards - towards the "back". Layer 0 is always the "front" layer, layer 1 is "behind" this, layer 2 "behind" that, etc. You can add layers at the front or back, literally as many as you like. Normally you will only see the front layer, unless you apply a transition or a compositor (see section 11.14 and section 11.16).
You can zoom in and out of the timeline with the menu options View -> Zoom in, and View -> Zoom out, or with the key combinations ctrl-+ and ctrl-- (control and plus, and control and minus).
At the top of the timeline area are two spin-buttons. These show the region start and end points (see section 11.10).
The message area is the same as in clip editing mode, and shows information about your actions. You can call up the entire message log from the View menu; View -> Show Messages.
If you switch to expanded view, the context window will be hidden, and the preview window and polymorph window will expand. You can switch to expanded view either by:
press the d key once deselect the menu option View -> Compact view or, click on the Expanded View button.
press the d key once select the menu option View -> Compact view
If you insert a clip, you can always "undo" it from the Edit menu.
If you drag a clip onto the header part of the clip, it will be inserted from time 0.
When you have inserted a clip, it becomes a block. Blocks are the smallest unit in the LiVES multitrack editor. A block can vary from 1 frame to any number of frames. Currently, all frames in a block must come from the same clip. Tip: There are two types of blocks in LiVES - ordered blocks and unordered blocks. Ordered blocks have incrementing frame numbers, and these are what you get if you insert a clip from the clip area. Unordered blocks have frame numbers which jump around. Unordered blocks can be produced by the event recorder. There is not yet much support for unordered blocks in LiVES, but there may be in the future.
If you selected audio track per video track in the Multitrack settings, then any audio for the clip may be inserted with the clip. This is dependant on the Audio Insert Mode (see section 11.8). You can view the audio by clicking on the small arrow next to the track header.
Fig 11.3.4 a video track with audio If you are working with a backing audio track, you can drag a clip onto the backing audio, and the audio from that track may be inserted there too. Alternately, you can make the backing audio track the current track and press ctrl-i to insert the current clip.
Note: By default, when you insert, only the part between the start frame and end frame (the selection) is inserted. You can set these in the Clip Editor. To override this behaviour, you can select the menu option Edit -> Ignore selection limits when inserting.
Only the front-most (non-empty) video track is visible and its associated audio is audible. If you want a track behind this to be visible, you will have to apply a transition or a compositor (see section 11.14 and section 11.16). If you want audio from a track behind to be audible, you will have to apply a video/audio transition, or apply an audio only transition (see section 11.14 and section 11.15). The backing audio is mixed down with audio from the other tracks (see section 11.19). Remember, you can zoom in and out of the timeline with the menu options View -> Zoom in, and View -> Zoom out, or with the key combinations ctrl-+ and ctrl-- (control and plus, and control and minus).
press the 'p' key onc, or use the menu option Play -> Play from Timeline Position, or click on the Play all icon in the toolbar
press the 'q' key once, or use the menu option Play -> Stop, or click on the Stop icon in the toolbar
press the 'p' key once during playback, or use the menu option Play -> Pause, or click on the Pause icon in the toolbar
Pause is similar to stop, except that the timeline position is kept at the same point rather than rewound to the previous position.
The timeline position is the point from which playback will begin. It is also the point at which effects can be listed and edited. The timeline position can be set in the following ways:
click once in the timeline area use the menu option Selection -> Copy -> Region start to timecode (see also section 11.10) use the menu option Selection -> Copy -> Region end to timecode (see also section 11.10) use the menu option Edit -> Jump to next block boundary, or press ctrl-l use the menu option Edit -> Jump to previous block boundary, or press ctrl-j
ctrl-left and ctrl-right will move the timeline pointer left or right by one second at a time shift-left and shift-right will move the timeline pointer left or right by one frame at a time
Inserting or moving a block on the timeline will also cause the timeline pointer to move.
press the 'w' key until the start is reached use the menu option Play -> Rewind, until the start is reached click on the rewind icon in the toolbar until the start is reached
Tip: during playback, the cursor will sometimes disappear off the screen. You can eliminate this by selecting the menu option View -> Scroll to follow playback. You can also centre the timeline on the cursor using the menu option View -> Center on cursor, or by pressing ctrl-c.
In Multitrack Mode, there is also a separate window/full-screen mode. to activate separate window mode:
press the 's' key once or select the menu option Play -> Play in Separate Window
press the 's' key once or deselect the menu option Play -> Play in Separate Window or click once on the Separate window icon in the toolbar
Note: the window can be sticky (window is always shown, even when not playing), or not sticky (window is destroyed when not playing). To Toggle between these modes, use the menu option Play -> Separate Window 'Sticky' Mode, or press the 't' key.
Note: in multi-head mode, the Multitrack window can be in one monitor, and the playback window in another monitor. See also section 2.8.
press the 'f' key once or select the menu option Play -> Full Screen
press the 'f' key once or deselect the menu option Play -> Full Screen
Note that in the Multitrack Editor, full-screen mode is only activated for the separate window. Remember also that in the Clip Editor, video playback plugins become active when playback is in full screen, separate window mode. The same is true in Multitrack Mode.
There is only one type of loop mode available in the Multitrack Editor - continuous looping.
press the 'o' key once or select the menu option Play -> Loop Continuously or click once on the loop icon in the toolbar
press the 'o' key once or deselect the menu option Play -> Loop Continuously or click once on the loop icon in the toolbar
press the 'z' key once or select the menu option Play -> Mute or click once on the mute icon in the toolbar
press the 'z' key once or deselect the menu option Play -> Mute or click once on the mute icon in the toolbar
Note: if you are using jack audio playback, the overall audio volume can be adjusted from the toolbar audio slider.
use the menu option Tracks -> Add Video Track at Rea use the key combination ctrl-shift-t
use the menu option Tracks -> Add Video Track at Front use the key combination ctrl-t
Tip: if you increase the number of video tracks, you may wish to increase the number of tracks which are visible on the screen. You can adjust this using the menu option View -> Maximum Tracks to Display, and entering a new value.
With the polymorph window in in/out mode, the start and end points can be adjusted using the spin-buttons. The start and end points can be anchored in time using the Anchor start and Anchor end buttons.
If you select an audio block on the Backing Audio track, there are some additional options available. You can set the playback velocity from 0.5 (half speed) up to 2.0 (double speed). You can also reverse the audio playback by checking the Reverse playback box.
right click inside the block and select Split block here use the menu option Tracks -> Split current track at cursor press the key combination ctrl-s
To split several video tracks at the same point in time, select the tracks which you want to split, and then activate the menu option Tracks -> Split selected video tracks. Note: To select a video track, click in the check box at the very left of the track (see also section 11.10).
right click on the block, and select Delete this block select a block by double clicking on it, then use the menu option Edit -> Delete selected block select a block by double clicking on it, and then pressing ctrl-d
Deleting and splitting of blocks can be undone/redone from the Edit menu.
Note: if you delete a video block, and it has an associated audio block with it, the audio block will also be deleted. However, the reverse is not true - it is possible to delete an audio block without deleting its associated video block.
Most of this manual assumes that the mouse mode is set to Move. Select mode is used for selecting a region, and is described in section 11.10.
Snap Mode is used for positioning blocks on the timeline. If the Snap Mode is off, blocks are placed at the position they are dragged to, and remain in that position. If Snap Mode is on, then any newly inserted or moved blocks are moved as far to the left (start of the timeline) as possible, closing any gaps. Also, if a block is deleted, all blocks to the right on that track are moved to the left, closing the newly formed gap.
Audio Insert Mode only appears if you selected to have an audio track per video track. There are two settings, Insert with audio, and Insert without audio. As the names suggest, these options affect inserting of clips on the timeline (see section 11.3).
You can change Mouse Mode, Snap Mode and Audio Insert Mode by clicking on the drop down list and selecting a new value.
11.10 Regions
A region in LiVES, is defined as 1 or more video tracks and a time period. Regions can be used as the basis for many of the operations in LiVES. There are a couple of ways to create a region in the Multitrack Editor. One way is to select some video tracks, and select a time region; the other way is to switch to Mouse Mode select, and select a region with the mouse.
you can select/deselect an individual video track by clicking in the small checkbox at the very left of the timeline area.
You can select/deselect the current track with menu option Selection -> Select Current Track, or with the key combination ctrl-space.
You can select all video tracks with the menu option Selection -> Select all video tracks
You can deselect all video tracks with the menu option Selection -> Select no video tracks
Select all time with the menu option Selection -> Select all time, or the key combination ctrl-a
Select from zero time with the menu option Selection -> Select from zero time
Select to the end time with the menu option Selection -> Select to end time
Select from the current playback position using the menu option Selection -> Copy -> Timecode to region start
Select to the current playback position using the menu option Selection -> Copy -> Timecode to region end
If you put the Mouse Mode into Mouse Mode Select, then you can click and drag on the timeline area to create a selection. Note that with this method, you can only select adjacent video tracks. If you wish to select a time-period corresponding to the overlap between the selected tracks, this can be done by selecting the menu option Selection -> Snap to overlap. This option can be very useful indeed.
Note: the backing audio track cannot be selected. There are separate tools to deal with this track.
A gap is a space in a video track with no video or audio. If there is a non-blank track
behind this, video and audio from behind will be visible. Otherwise the viewer will see
black frames and hear silence (or only the backing audio).
You may wish to create a gap to insert other material into the track.
You can insert a gap in the current track over the selected time by activating the
You can insert a gap in all selected tracks over the selected time by activating the
Effects are moved with blocks where possible, except if the menu option Effects ->
Gaps can also be removed, for example, if you deleted a block and you want to close
the gap.
To remove the first (earliest) gap(s) in a region, use the menu option Tracks -> Close
To remove all gaps in a region, use the menu option Tracks -> Close all gaps in
To remove part of a gap, you should make sure that the selected time starts or ends at the point of removal (see fig. 11.11.1).
Note: Gap insertion and removal can be undone and redone from the Edit menu.
For this example, we will choose the "colour correction" effect because it has parameters. Some effects do not have parameters, and they are simply applied to the block or region as-is. When you click on an effect with parameters, the polymorph window will go into effect mode. You will also see a frame preview in the preview window. Effects can be applied to a block or to a region. If you have a block selected, you can go to the effects menu, and select "apply effect to block". If you have a region selected the effects available depend on the number of tracks in the region. For two tracks, you can apply a transition (see section 11.14). For two or more tracks, you can apply a compositor (see section 11.16). For a single track, you can apply an effect. Use the menu option Effects -> Apply effect to block.
For this example, we will choose the "colour correction" effect because it has parameters. Some effects do not have parameters, and they are simply applied to the block or region as-is. When you click on an effect with parameters, the polymorph window will go into effect mode. You will also see a frame preview in the preview window.
Effects can be applied to a block or to a region. If you have a block selected, you can go to the effects menu, and select "apply effect to block". If you have a region selected the effects available depend on the number of tracks in the region. For two tracks, you can apply a transition (see section 11.14). For two or
more tracks, you can apply a compositor (see section 11.16). For a single track, you can apply an effect. Use the menu option Effects -> Apply effect to block.
For this example, we will choose the "colour correction" effect because it has parameters. Some effects do not have parameters, and they are simply applied to the block or region as-is. When you click on an effect with parameters, the polymorph window will go into effect mode. You will also see a frame preview in the preview window.
We will first set the parameters at the start of the effect. We can do this by sliding the small slider under the parameters all the way to the left.
Fig. 11.12.2 - slide the time slider to the left Tip: notice the timeline cursor moves with the effect time slider. You can also move the timeline cursor which will set the effect time slider.
You can then adjust the parameters, and preview them by pressing the Show Frame
Preview button. (Generally, the Auto preview button is checked, and it is not necessary to actually click the Preview button any more).
Fig. 11.12.4 - the Show frame preview button and Auto preview
When you are happy with the values, you can press the Apply button.
We will now set the values at the end of the effect. Slide the effect time slider all the way to the right. Then adjust and preview the values, and when you are happy click on Apply again.
If you now move the slider back and forth, you should see the values changing smoothly. This is known as "parameter interpolation". You can preview at any point by pressing Show frame preview (or if Auto preview is checked, you will automatically see the preview). Tip: Each time you click Apply, LiVES adds or alters an existing Parameter Change Node in the timeline. In effect edit mode, there are two buttons below the effect parameters which will allow you to move instantly between these Nodes. These buttons are labeled Prev. Node and Next node. Clicking on these buttons will move you between existing Parameter Change Nodes for the effect being edited. At these Nodes you can alter the parameter value(s), or you can delete the Node by pressing Del. Node.
If you now play back the layout (by pressing 'p'), you should see the colours in the clip changing ! You can add more effects on top of the colour correction if you wish. You can undo and redo adding of effects using the Edit menu.
Right click on an audio block, and select Adjust audio volume and pan Right click on an audio block and select List effects here, then double click on the audio volume and pan tab in the polymorph window, or right click on it and select View/Edit this effect. Click inside an audio block, then activate the menu option View -> Effects at current, or press the 'e' key, then double click on the audio volume and pan tab in the polymorph window, or right click on it and select View/Edit this effect.
Just as with a video effect, the time slider can be used to select a point in time (see section 11.12). After selecting a point in time, you can set values for volume and/or pan at that point, and then click on Apply to store those values. Note that parameters for audio effects are interpolated in the same way as parameters for video effects. In a similar way to video effects you can jump between parameter nodes to edit or delete them (see section 11.12).
Now, slide the effect time slider to the right, and click on Transition Out. Transition Out means that all of the rear layer (in this case, layer 1) is visible. Then click on Apply again.
Now when you play back, you will see frames smoothly transition from layer 0 to layer 1.
Some video transitions also allow crossfading of audio, provided per-track audio is enabled. These are marked Audio/Video transitions in the menu options, ie. Effects -> Apply effect to region -> Transitions -> Audio/video transitions. For these types of transitions, you will see an extra checkbutton, Crossfade audio. Checking this button will cause the audio to crossfade in proportion to the video transition. For example if you fade (chroma blend) from the front layer to the layer behind, checking this button will cause the audio to fade from the front layer to the next layer.
11.16 Compositor(s)
A compositor takes any number of video inputs and mixes them down to a single track. The output is always on the front-most layer of the compositor.
First you need to create a region (see section 11.10) to apply our compositor to. Select one or more tracks, either by checking the boxes on the left, or from the menu option Selection/Select all video tracks.
Now select a time region by dragging on the timeline header. If Selection -> Snap to
overlap is on, only the region of overlap between the selected tracks will be selected.
Now click on Effect -> Apply effect to region, and pick "compositors". Select the compositor you wish to apply. The polymorph window will go into effect mode. In this example we will use the compositor named "compositor".
Now, you need to know where the timeline cursor is, and also which track is the "current track". If you look in fig. 11.16.3, the current track is layer 2 (because it is a different colour to the rest). You can change the current track by clicking on its label, or by using ctrlup and ctrl-down.
Depending on whether there is a frame present or not at the current time/track coordinate you will see one of two things. If a frame is present, you will see frame settings (x start, y start, x scale, y scale, alpha) and the background colour control. If no frame is present, you will see only the background colour control. Try moving the timeline cursor and current track so you can see both things.
If a frame is present, you can also click and drag on the preview window to set the xstart, ystart, xscale, yscale and alpha values.
Fig. 11.16.6 - preview window can be used to "draw on" for the compositor
Note: parameters xstart, ystart, xend, and yend and alpha, are set independently for each track in the compositor. Clicking on Apply only sets these parameters for the current track.
The parameters of compositors are also interpolated, so for example, you can make a clip move around, or fade in and out.
right clicking on a point on the timeline and selecting List effects here. make the track you want current, select a point on the timeline, and activate menu option View -> Effects at current make the track you want current, select a point on the timeline, and press the 'e' key
The list of effects at the chosen point will appear in the polymorph window. Once you have listed the effects, assuming there are some effects, you can make one of them current. This is done simply clicking on the effect name in the polymorph window. If an effect is selected, it can be moved, edited, or deleted. Moving effects in the stack is discussed in section 11.18.
right click on the effect name in the polymorph window, and select Delete this effect
or, click once on the effect name to select it, then activate the menu option Effects -> Delete selected effect
If an effect is deleted, this can be undone and redone from the Edit menu.
or, right click on the effect name in the polymorph window, and select View/Edit this effect
or, click once on the effect name to select it, then activate the menu option Effects -> View/Edit selected effect
Remember, if you edit an effect and change any of its parameter values, you need to click on Apply for those changes to be recorded. See also section 11.12.
LiVES will attempt to preserve this order in all filter maps for as long as both effects are active. Therefore, you will generally only need to make the change at the first filter map, unless you want to change the order again. Changing the order of effects can be undone and redone from the Edit menu.
In the audio mixer, you can adjust the levels of the backing track (if present), and the audio for each layer. You can adjust the volume levels of each layer independently by moving the sliders up or down.
There are two check buttons which can be set or unset. Gang layer audio causes all of the layer (i.e. not backing track) audio to be set to the same level. Invert backing audio and layer volumes - this can only be set if gang layer audio is activated. With this set, increasing layer audio will decrease the backing track audio level, and vice-versa. This is done in such a way that they will always add up to 1.0 if possible. In this way, you can raise or lower the volume of the backing track relative to the layer audio, in theory without causing clipping (overdrive) of the audio levels. There are two buttons at the bottom of the mixer, Reset values - this button will reset the values back to where they were when the mixer was opened, and Close mixer, which will return you to the Multitrack Editor window. The key combination ctrl-m will also close the mixer window.
To clear all marks from the timeline, use the menu option Edit -> Clear marks from timeline.
You can reload a layout using the menu option File -> Load layout, and then selecting a layout to load. If there is a current layout already in the timeline, you will be prompted to Save the current layout, Wipe it, or Cancel. If the new layout was saved with width, height and audio values, these values will be used, unless the menu option File -> Ignore width height and audio values from loaded layouts, is selected. Once the layout is loaded, it will be checked for errors - for example missing clips or frames, and if any such errors are found, they will be corrected in as much as is possible. In the case of errors which are corrected, you will be asked if you want to overwrite the layout on the disk with the corrected version. The layout will then be displayed in the timeline.
Layouts can be wiped or deleted in the following way: either exit from Multitrack mode (see section 11.23), or activate the menu option File -> Wipe/Delete layout. If the layout has not been saved you will be given the option to save it, or to wipe it from the timeline. If the layout was previously loaded from or saved to disk, you will be given the option to wipe it from the timeline, or delete it completely from the disk.
Note: wiping or deleting a layout cannot be undone, so exercise caution when using this option.
11.22 Rendering
Rendering a layout is done via the menu option Render -> Render all to new clip. If you deselect Render -> Render audio, only video will be rendered. If you deselect Render -> Render video, only audio will be rendered. (It is not possible to have both settings deselected at once !)
Rendering, resizing, resampling and applying effects are all done in one pass. The result of the rendering will be a new clip.
Once rendering is finished, either you will exit Multitrack or you will see the newly rendered clip appear in the clip list. This action is dependant upon a setting in Preferences (Tools -> Preferences -> Exit multitrack mode after rendering).
After rendering, if the Preference Exit multitrack mode after rendering is set.
By activating the menu option Edit -> CLIP EDITOR, or with the key combination ctrl-e
Using the menu option File -> Quit, or pressing the key combination ctrl-q
Upon exiting Multitrack Mode, if there is a unsaved layout in the timeline, you will be prompted whether to save the layout or not. There is also the option to auto-reload the layout each time you return to Multitrack mode. This is useful if you are working on the same layout each time. If you choose to save the layout, you will be prompted for a filename to save it to. For more on saving layouts see section 11.21. You can choose not to be shown this warning. The warning can also be deactivated/reactivated from Tools -> Preferences -> Warnings.
When a layout is saved, LiVES also saves a record of what clips were used in that layout, the highest frame number, frame rate, the length of any audio used and so on. Then, if any changes to these clips are made in the Clip Editor, LiVES is aware that this may affect one or more layouts. A warning will be shown allowing you to abort the operation or to go ahead anyway.
If you choose to go ahead, after the operation, you will see the Layout Errors window. This informational window shows a list of all affected layouts. You can choose to Close or Clear this window, or you can choose to Delete the affected layouts from the disk.
If there are messages in the Layout Errors window, you can view these at any time by activating the menu option Info -> Show layout errors.
In Preferences, you can choose which kinds of actions will produce a warning: (The following are highly recommended, as ignoring them can lead to missing data in layouts)
The following are optional, by default they are not set. You can set them if you want to ensure that your layouts are never altered:
Layouts are also considered part of a Project, and are saved and loaded inside LiVES project files. See section 4.8.
This option is used mainly for debugging purposes, but it may be of interest to see how LiVES stores a layout internally. For more technical details, see section 17.3.1.
In future versions of LiVES it may be possible to manipulate the event list directly. There are also plans for plugins which will create and alter the event list in real time (timeline plugins).
LiVES can stream its video output to another copy of LiVES using LiVES to LiVES streaming. Since this is still very much a work in progress, streaming of audio is not yet possible. On the source machine, use the Clip Editor menu option Advanced -> Send LiVES Stream to., or you can select the lives2lives_stream playback plugin in Preferences, and click on the Advanced button.
Enter the desired frame-rate, width, height, colourspace, and the IP address and port of the target machine. Start with a low frame-rate and small frame size. The video output will be streamed whenever LiVES is playing back in fullscreen/separate window (fs) mode.
On the receiver machine, use the menu option Advanced -> Receive LiVES stream from. You can either choose to accept streams from any host, or you can specify a host by entering its IP address. You can also specify the port to listen on. This must be the same as the port of the target machine, above.
The receiver machine will then wait for incoming frames. You may need to adjust the receive buffer size as root, you will get a message informing you of this if it is the case.
Frames are sent via UDP. You may need to check your firewall settings to make sure the connection is not blocked. On the target machine, the incoming stream is treated like a generator. You can apply more effects to it, mix it with other clips and record it.
Streaming IN There are several things you can do at this point. One is to play and mix an incoming stream, if using yuv4mpeg, for example from mplayer: (the examples assume that LiVES temporary directory is /tmp/livestmp, you will need to adjust this as necessary.) mkfifo /tmp/livestmp/stream.yuv lives & cd /tmp/livestmp mplayer -vo yuv4mpeg:file=/tmp/livestmp/stream.yuv /some/video/file In LiVES, activate the menu option Advanced -> Open incoming stream; the mplayer stream will now display in the LiVES window. Presto, you can add video effects to a realtime video stream !
Streaming OUT For outgoing streams, the process is also very simple. For yuv4mpeg, LiVES will create a yuv4mpeg stream on stdout. So for example, you can do: lives-exe | yuvplay In LiVES, go to Tools -> Preferences -> Playback and select the yuv4mpeg_stream plugin. If you don't see the plugin, you probably need to recompile LiVES with mjpegtools support. Once that the plugin has been selected, whenever you play in LiVES in full screen/separate window (fs) mode, the output will appear in the yuvplayer window.
Theora streaming Theora streaming should be possible using the yuv4mpeg stream plugin. E.g: lives | ffmpeg2theora -f yuv4mpeg -a 0 -v 5 -o /dev/stdout - | oggfwd iccast2server 8000 password\ /theora.ogg
The RFX specification is shown in section 17.3.2. LiVES has an RFX builder tool, which can be used to help create or customise rendered effects,transitions,tools,utilities and generators. Any of the builtins can be copied, so you can see how they work, or create custom versions. In the menu option Advanced -> RFX Effects/Tools/Utilites, there are various suboptions
New test RFX script Copy RFX script to test Edit test RFX script
Select whichever option is applicable. In the case of copy, you can copy any builtin, custom or test script.
Script Status
builtin : factory supplied defaults. These can be copied to test but not edited directly.
test : test scripts can be created and edited by the user. Once editing is complete, test scripts can be promoted to Custom status.
custom : custom scripts can be imported and exported. There is a section on the LiVES homepage with links to Custom RFX scripts.
Type
The first field in the LiVES rfxbuilder window is type RFX scripts in LiVES are divided into types, those types are currently:
Effects Effects take one input frame at a time and produce one output frame. Frames may not be resized, nor may the palette or image type be altered. You must produce the output frames in order, and you may not skip an output frame. In LiVES, an effect is applied to a selection of a clip. Tools Tools take one input frame at a time and produce one output frame. Frames may be resized, but the palette or image type be altered. If the frames are resized, they must all be resized to the same size. You must produce the output frames in order, and you may not skip an output frame. In LiVES, a tool is applied to an entire clip. Transitions Transitions take two input frames at a time and produce one output frame. The output frame must be the same size as the first input frame, and the palette and image type of the output frame must match that of the input frame. You must produce the output frames in order, and you may not skip an output frame. In LiVES, a transition is between the clipboard and a selection of a clip. Generators Generators produce images. Frames must be all of the same size and numbered in sequence. You should produce the output frames in numerical order.
There are two types of generator - batch generators and non-batch generators. Batch generators produce all of their frames in one go, non-batch generators use the loop code to produce one frame at a time. Utilities Utilities do not process frames, but they may take advantage of the parameter window system in LiVES, and may execute code when they are activated.
Name
The next field in the rfxbuilder window is Name. Here you enter the name of your plugin. Note that spaces are not allowed in the name, and the name must be unique amongst all plugins loaded on the particular LiVES system. LiVES uses the name field when generating a plugin from the script. LiVES also uses the name field to prompt for a default script name: name.script
Version
This takes an integer value for the plugin version.
Author
Freeform author field. Mandatory.
URL
Optional field for author's URL.
Menu text
This field is mandatory. Here you enter a text string which should identify this script's plugin in a menu. Underscores represent mnemonic keys in the name.
Action Description
This field does not appear for utilities. For other RFX types, it is mandatory. It should describe actively what the plugin is doing to frames/data in the present continuous tense, the first word only capitalised, e.g. Edge detecting. This text appears in various places in the LiVES GUI.
Minimum Frames
This field does not appear for utilities. For other RFX types, it is mandatory. It informs LiVES what is the minimum number of frames this tool/effect can be applied to. Normally the default setting of 1 is acceptable. The next most important field depends on the RFX type. For Utilities it is Triggers, for all other RFX types it is the Loop code.
Loop Code
The objective of the Loop code is to create an output image. How this image is created is left to the discretion of the plugin author. However, note the rules described under the type entry above. The means of achieving this objective depends on the Language Code. Currently in LiVES, the Language Code is fixed as LiVES-Perl. However, other languages may be used in the future since the system is extendible via plugin builders. The following however, assumes that your plugin is written in LiVES-Perl. You should refer also to the LiVES-Perl user guide.
Effects : you must produce the output frame called $out. The image size (width and height) of $out must match the image size of a frame called $in. This image size is given as $width and $height. The palette/image type of $out must match that of $in, even if the file extension of $out does not match that of $in. You may not change $in, but you may copy it to produce $out.
At the very least, your plugin should copy $in to $out: `cp $in $out`;
You may use any command on the system as a frame effect, via the Perl system command.
Tools : you must produce the output frame called $out. The image size (width and height) of $out may vary, but all frames processed between pre and post (see below) must be of the same size. The input image size is given as $width and $height. You should set $nwidth and $nheight to the new width and height of $out, even if you do not resize. The palette/image type of $out must match that of $in, even if the file extension of $out does not match that of $in. You may not change $in, but you may copy it to produce $out.
At the very least, your plugin should copy $in to $out: `cp $in $out`;
You may use any command on the system as a frame effect, via the Perl system command.
Transitions : you must produce the output frame called $out. The image size (width and height) of $out must match the image size of a frame called $in. This image size is given as $width and $height. The palette/image type of $out must match that of $in, even if the file extension of $out does not match that of $in. You may not change $in, but you may copy it to produce $out. For transitions, there will be an additional frame, $in2 with $width2 and $height2. At the very least, your plugin should copy $in to $out: `cp $in $out`;
You may use any command on the system as a frame effect, via the Perl system command.
Generators : Batch mode generators should produce all their frames at once, these should be numbered in sequence. non batch-mode generators must produce the output frame called $out.
Some variables must be set for non-batch mode. $end must be set to the number of frames to be generated. $nwidth and $nheight must be set to the image size.
Optionally (for batch and non-batch mode): $fps can be set to the frame-rate. If this is not set the host will set its own frame-rate. Any user settable parameters can be defined in the Parameter section of the RFX builder window. These parameters are referred to in LiVES-Perl as $p0, $p1, $p2, etc. in the pre/loop/post/trigger code. Any variables set in the Loop code are available in the Post code also.
Pre Code
This code is run before the Loop code. In here you can enter any code which should only be done once for a processing block, e.g. initialising values, setting $nwidth and $nheight for a Tool. Any variables set in the Pre code are available in the Loop code and in the Post code.
Post Code
This code is run after the Loop code. In here you should remove any temporary files which were created in the Pre or Loop sections.
Parameters
This section is used to define the user changeable parameters which will be used in the Pre/Loop/Post/Trigger code. These parameters are referred to in LiVES-Perl as $p0, $p1, $p2, etc. For the variable type colRGB24, the parameter is split, e.g. $p0_red, $p0_green, $p0_blue. Here you define the name/label, type, minimum, maximum, and other details for those parameters. When the RFX plugin is activated, the user will be presented with a window which allows them to enter the parameter values. The parameter types currently are:
bool : boolean num : numerical (int or float) string colRGB24 : red, green and blue values each of which ranges from 0 255 string list : the value is an integer (0 based index in list)
Name/Label This is the text which appears next to the parameter entry in the parameter window. This is a mandatory field for all parameter types.
Button Group Use of a non-zero button group implies that only one parameter in that group (the active parameter) can take its non-off value. Off value is defined as zero for bool type parameters, default value for all other types. One effect of setting the group in LiVES is to turn bool type parameters from check buttons into radio buttons. Usually this can be left as 0.
Decimal Places This field only exists for num type variables. The effect is to make a parameter either an integer (a zero value) or into a floating point parameter (a non zero value).
Default Value In LiVES, this is the value which is set when the plugin is first loaded. Setting the value in the init trigger will also set the default (see below). For variables of type colRGB24, there are separate default values for red, green and blue.
Minimum Value This field only appears for parameters of type num. It represents the minimum value of the parameter. Note that this value can be altered in the init trigger (see below).
Maximum Value This field only appears for parameters of type num. It represents the maximum value of the parameter. Note that this value can be altered in the init trigger (see below).
Maximum length This field appears only for parameters of type string. It allows you to set a maximum length for a string parameter. For LiVES-perl, the absolute maximum is 1024 characters.
Set default This button appears for string type parameters only. Clicking on it allows you to set a default value for the string parameter. Any text entered will be truncated to the maximum string length (see above).
String Lists For string_lists, you may enter values on separate lines. The default can be selected from the list.
layout special
In LiVES, layout defines a horizontal row within a vertical box of parameters. Special links together certain of the parameters with external (to RFX) widgets. There are 3 types of Special widgets currently defined in LiVES:
These will be described in more detail below. First we will look at the layout keyword. Every layout keyword is followed by a layout row. In LiVES these layout rows are drawn in order from top to bottom. Any parameters which are not in a layout row are positioned below the last layout row. A layout row can consist of: hseparator or a mixture of parameter position (e.g. p0) a label (e.g. label) a blank space for padding (fill) followed by a repeat number (e.g. fill2). If the number is 1 it can be omitted (e.g. fill). Each field in the row is separated by a |. Field separators within quotes are ignored. An example of a layout row might be: width|p0|fill|X|fill|height|p1| In LiVES this would produce a row that looks like: a label width; the first parameter; some padding; a label X; more padding; a label height; the second parameter The outcome is undefined if you try to position a non-existent parameter. This should be avoided. The first parameter is p0, the second, p1, etc.
Special Widgets
A special widget can be used to link parameters together, possibly with external values. In LiVES there are currently 3 types of special widgets. Some types have subtypes. Each special widget is explained below. The format for the linked parameters is currently (for example if there are 4 linked parameters): 0|1|2|3| which would link parameters 0,1,2 and 3 to a special widget.
Special Type Aspect This is a special widget which links together two num0 parameters in such a way that the ratio between the two parameters will always be the same as the width/height
ratio of the current clip. This action is controlled by a checkbutton. The aspect widget will also set the default values for these two parameters to the current clip width and height, You should make sure both linked parameters are of type num. Special Type Framedraw This is a special widget which has subtypes. The number of linked parameters, and the way they are linked depends on the subtype. Note: If a linked parameter is a float, then the value represents a ratio (e.g. 1.0 = full frame width). If a linked parameter is an int then the value is in pixels. In the latter case the host should set the maximum value as appropriate.
Framedraw subtype rectdemask This subtype of framedraw links together four num0 parameters. The parameters are linked in such a way that they represent start/end x/y values for an unmasked rectangle, drawn over a frame from the current clip. If any of these parameters are changed, the unmasked rectangle also changes. This usbtype will also set minimum, maximum and default values for the four linked parameters.
Framedraw subtype multrect This subtype of framedraw allows multiple rectangles to be drawn. It links four numeric parameters. The params represent start/end x/y values. The numeric parameters are multivalued, each rectangle is formed by the nth values of each parameter. Framedraw subtype singlepoint Links two parameters. They represent a single point on the frames. This can be marked by crosshairs, etc.
Special type audiochannel Links 1 or more parameters. Any parameter marked with this should have 1 value per audio channel. For example it could be a volume level for an audio mixer.
Special type fileread Links 1 parameter of type string. This parameter should be empty or point to a file to which the user has read permissions.
Special Type transalign The transalign special widget links together two num type parameters. It has two states. In one state it will set the first parameter to its minimum value and the second parameter to its maximum value. In the second state it will do the opposite, set the first parameter to its maximum, and the second parameter to its minimum. In LiVES the two states are controlled by two radio buttons, with labels align starts and align ends. It is generally used for transitions.
Requirements
In this table you can enter the binary requirements for the plugin. If any of these binaries are missing, the plugin will give an error and will not run. This field is not present for utilities.
Properties
Here you can enter the properties for the script. This is optional. LiVES will set some hidden properties depending on the RFX type. Currently changeable properties are: slow this is a hint to the interface that the effect/transition runs slowly. batch mode generator this is only for generators, and must be set if the generator runs in batch mode.
Triggers
In the trigger table, you can enter code which should be executed either when the effect is activated, or when a parameter value is changed. For a Utility, any code to be executed must be entered in the init trigger. Refer to section 17.3.2.1 for details of how triggers are coded in LiVES-Perl.
option Advanced -> Rebuild all RFX plugins.You need to do this each time you make a change in the script. The new plugin should then appear under Advanced -> Run test rendered effect/tool/generator. From here you can run it. Once you are happy with your plugin and have finished tweaking it, you can promote it to a Custom plugin. This is done with the menu option Advanced -> RFX Effects/tools/utilities -> Promote test rendered effect/tool/generator. Custom effects can be exported and imported into other copies of LiVES. See section 4.12.6 (Installing custom effects).
16 Preferences
Here follows a description of all of the Preferences in LiVES. Preferences can be activated using the menu option Tools Preferences, or by pressing the key combination ctrl-p.
GUI
Open file selection maximised controls whether the file selector for opening new media uses the full size of the screen or not. Show Recent Files in the File Menu if this is checked, newly open files are shown under the menu option File Recent Files. This functionality can be disabled for privacy or other reasons. Stop screensaver on playback if checked, LiVES will attempt to stop screensavers from activating when LiVES is playing back video. Open main window maximised controls whether the mainw interface window is the full size of the screen or not. Show toolbar when background is blanked controls whether the toolbar icons are shown when the clip editor is playing back in full-screen, internal window. These icons can proved a key guide for novice users. Multi-head support These preferences are only active if LiVES detects more than one monitor attached. Force single monitor mode check this if you want LiVES to ignore monitors other than the main monitor. Monitor number for LiVES interface allows selection of a monitor for the main LiVES interface Monitor number for playback allows selection of a monitor for playback in separate window mode (see section 4.10.4). A setting of zero will force fullscreen/separate window mode to stretch across all monitors.
Decoding
Video open command this entry can be used to customise the command used to open/import video.
Open/render compression here you can enter a value which indicates how much the frames will be compressed by when opening or rendering. For jpeg this is a lossy compression, for png it is lossless. A higher value will use less disk space, but will result in poorer quality images (jpeg) and possibly slower response (jpeg/png). Default image format this is the format that LiVES imports video frames in. The default is jpeg, but it is also possible to work with png images (although it is not possible to mix the two types). If you change this to png, you will also need to make a change in smogrify, $img_ext=.png instead of $img_ext=.jpg. Use instant opening when possible if this is set, then video files of certain types will be opened/imported immediately, rather than having each frame decoded. At the time of writing this is available for ogg/theora and dv video files. Enable automatic deinterlacing when possible if this is set then instant opened files which are interlaced will be automatically deinterlaced. This is used for example for dv type material loaded from video cameras. When opening multuple files, concatenate images into one clip. This instructs LiVES how to handle when multiple files are selected for opening. If this option is checked then any images loaded will be concated into one file. If it is unchecked then each image is loaded in as a clip with one frame.
Playback
Video settings Preview quality here you can select the level of quality for previews. The default is normal, which should suffice in most situations. If you have a slower machine you can set this to low and it may help performance conversely if you have a very fast machine, then you may wish to set this to high, although the difference will be minor in this case. Show fps statistics if checked, LiVES will show details of the average real playback rate in the message area. This can be used for performance monitoring purposes. Plugin here you can select the video playback plugin, if any. Clicking on the advanced button allows you to view or alter any parameters specific to that plugin. Note again that video playback plugins are only active in full-screen, separate window mode. See also section 4.10.6.
Audio settings Audio player here you can choose which audio player to use jack, sox or mplayer. Jack is recommended for professional or semi-pro work, but may not be
supported by all soundcards. In addition, jack is not very helpful when it comes to sharing soundcards with other applications. In case of problems with jack, you may want to set this to sox, which will give some sound support, albeit of a reduced level of functionality. Mplayer is not recommended and is kept in solely for test and lastresort purposes. Note: if switching permanently to or from the jack audio player, you may also wish to review the options in the Jack Integration tab of Preferences. Audio play command if an external audio player is used, you can adjust the audio player command here. Audio follows video rate/direction this option is only available with the jack audio player. If checked, then audio will follow the rate and direction of the video which is being played back. This is useful for trick-playing with audio and video. Audio follows clip switches again, this option is only available with the jack audio player. If checked then switching the foreground clip during playback will cause the audio track to also switch in sync with the video track.
Recording
Record audio when capturing an external window this option is only available when using the jack audio player. It affects external window capture (see section 4.2.8). The following options define what is recorded during record mode (see section 9). Frame changes these are always recorded; the option is only shown here as a reminder. FPS changes changes in velocity (frames per second) - these are always recorded; the option is only shown here as a reminder. Real time effects check this option to record real time effects, transitions and generators. Clip switches check this option to record clip switches Audio check this option to record audio and audio changes. Only available when using the jack audio player.
Encoding
Encoder here you can set the encoder for encoding. You will get the chance to change this again if you Encode clip as (see section 4.9). Debug mode this is very useful if you are having problems encoding. Set debug mode to on, and start LiVES from a terminal window (commandline). When you encode, there will be a lot of output produced in the terminal window which can help to track down and resolve the issue. Output format here you can select the (video) output format to encode to. Each encoder has its own set of formats, and the choice available is also dependent upon which other programs and libraries you may already have installed. Audio codec here you can choose the format for encoding the audio of a clip to. The choices are dependent on the encoder and video output format selected. Some formats do not allow encoding of audio at all.
Effects
Use anti-aliasing when resizing controls whether or not anti-aliasing (smoothing) is performed when frames are resized. Number of real-time effect keys sets the number of effect keys which can have effects bound to them. See section 7.1. The default value is 9, and the maximum is 64.
Directories
In this tab you can set various default directories for LiVES. Video load directory the default directory to load (import) video clips from. Video save directory the default directory to save video clips to. Audio load directory the default directory to load audio from Image directory the default directory for saving frame-shots to Backup/restore directory the default directory for backing up and restoring single
clips to (see section 4.2.9). Temp directory very important, this is where LiVES stores all open clips and sets. It should point to a directory on a partition with plenty of disk space. (It is not a good idea to leave it in /tmp on many systems, since this directory is frequently emptied on logout on many systems). The value should only be changed if there are no other copies of LiVES running on the same machine. LiVES will take care of migrating all sets from the old temp directory to the new one.
Warnings
Here you can define which warnings are show and which are suppressed. If a warning message was dismissed permanently, it can be re-enabled from here.
Misc
Midi synch this setting when activated, causes LiVES to emit a MIDI pattern start when playback starts, and a MIDI pattern end when playback is stopped. See section 10.6 When inserting/merging frames here you can select what action should be taken when inserting or merging frames from the clipboard into a clip with a different framerate. The default is to Resample the clipboard, but if desired, this action can be changed to Speed Up/Slow Down Insertion CD device here you can enter the path to your CD device. This is used for grabbing audio from CD tracks (see also section 6.2). Default FPS this is the frame rate which LiVES will default to when no frame rate is specified. For example when opening a stream with an unknown frame rate, when generating frames to a new clip, and no frame rate is specified, or when opening an image sequence.
Themes
In this tab you can select a new theme for LiVES. See section 10.3.
Streaming/Networking
Download bandwidth (Kb/s) here you can enter the speed of your network connection. This is only used for importing from remote URLs (see section 4.2.5).
Jack Integration
This tab can be used to set the level of integration with the jack audio connection kit. There are settings for the jack transport server and for the jack audio server. Currently the same server is used for both audio and transport. This may change in the future. Jack transport The following settings apply to the jack transport server: Jack transport config file this setting is reserved for future use and cannot be altered for now Start server on LiVES startup whether to start the transport server on LiVES
startup. Currently this is not needed if the jack audio server is set to startup. Jack transport master set whether LiVES is a jack transport master (see section 10.7). Jack transport client set whether LiVES is a jack transport client (see section 10.7).
Jack audio The following settings apply to the jack audio server: Jack audio server config file - this setting is reserved for future use and cannot be altered for now Start server on LiVES startup whether to start the jack audio server on LiVES startup. Currently this is not needed if the transport server is set to startup. Play audio even when paused if this setting is enabled (the default), LiVES will continue playing audio when video is frozen in the clip editor. This is overridden by the setting Audio follows video rate/direction. The other effect of this setting is to allow audio to be played back even when jack transport is not rolling - for this reason it is recommended to leave this setting alone, unless you specifically only want LiVES to play audio when jack transport is rolling.
Multitrack/render
When entering Multitrack mode: Prompt me for width, height, fps and audio settings allows a choice of frame size, frame rate and audio settings on each entry to the Multitrack Editor (see section 11.1). The values set below will still be used as the default values, but can be altered. Always use the following values do not prompt for values on entry to the Multitrack Editor, but always use the values set below. Note that some of the values may be overidden if a new layout is loaded (see section 11.21). Use these same values for rendering a new clip if this option is checked, then the values set below will be used for rendering to a new clip after recording (see section 9.1). If this is unchecked, the values set below will still be used as the defaults, but they can be changed.
Video settings Width enter the desired frame width in pixels Height enter the desired frame height in pixels FPS enter the desired frame rate in frames per second
Audio settings Enable audio deselect this option to disable audio altogether when in Multitrack Mode (or rendering, if appropriate). Rate enter the desired audio rate in Herz. Channels enter the number of audio channels desired. Sample size enter the desired sample size in bits per sample. Signedness enter the desired signedness. Endianness enter the desired endianness.
Audio channel settings Enable backing audio track check this option to enable the floating backing audio track. Audio track per video track allow one audio track per video track. This is in addition to any backing audio track.
Other multitrack options Undo buffer size (MB) this is the size of the undo / redo buffer in the Multitrack Mode, measured in megabytes. This value can be increased on systems with plenty of RAM memory, or reduced on systems where available memory is at a premium. Exit multitrack mode after rendering if checked, LiVES will return to the Clip Editor after rendering in Multitrack Mode. If unchecked, LiVES will remain in Multitrack Mode.
MIDI/joystick learner
Here you can enter some values for the MIDI/joystick learner (see section 10.5). Events to respond to Joystick events if checked, LiVES will respond to joystick events in the MIDI/joystick learner Joystick device here you can enter the path to your joystick device. In most cases, LiVES will autodetect this. MIDI events if checked, LiVES will respond to MIDI events in the MIDI/joystick learner Use ALSA MIDI - this option is only available from LiVES 1.1.0 and onwards, and only if LiVES was compiled with ALSA support. This option is recommended if available. You can also select raw MIDI if preferred. MIDI device here you can enter the path to your MIDI device. In most cases, LiVES will autodetect this. Only valid for raw MIDI.
Advanced MIDI check rate the number of MIDI checks per keyboard tick. Increasing this may improve MIDI responsiveness but may slow down playback. The default is 1000. Only valid for raw MIDI. MIDI repeat the number of non-reads between successive reads. Try adjusting this value if your MIDI device is not being read properly in the MIDI/joystick learner. The default is 1000. Only valid for raw MIDI.
17 Appendices
17.1 HOWTOs
17.2 Troubleshooting
I am using compiz, and the screen "blinks" in fullscreen mode.
In compiz configuration settings, uncheck "Unredirect Fullscreen Windows".
When I try to start LiVES with the jack audio player, it fails with a message "ALSA: Cannot open PCM device alsa_pcm for playback. Falling back to capture-only mode"
Make sure your user has full access to the soundcard. For example, in Ubuntu, go to the Users and Groups administration tool, and for your user, check the user privilege "Use audio devices".
I can load in video, but when I try to load or resample audio, it fails !
Make sure you have sox set up to handle .wav format. The package libsox-fmt-all is recommended.
This code is only required for Perl plugins which want to make use of the
LiVES backend (smogrify). This will create a non-standalone plugin (unless $standalone is set, e.g. for testing purposes). Otherwise, and for non-perl languages, we just parse the commandline and get the first parameter (the directive as $command). This will create a standalone plugin.
49 50 51 52
OK, here we have the first directive, version. We must print out the plugin version to STDOUT, and exit with a code of 0.
55 if ($command eq "init") { 56 # perform any initialisation needed 57 # On error, print error message and exit 1 58 # otherwise exit 0 59 if ($img_ext eq "png") { 60 if (&location("png2yuv") eq "") { 61 print "png2yuv was not found. Please install it and try again."; 62 exit 1; 63 } 64 } 65 else { 66 if (&location("jpeg2yuv") eq "") { 67 print "jpeg2yuv was not found. Please install it and try
again."; 68 exit 1; 69 } 70 } 71 if (&location("mpeg2enc") eq "") { 72 print "mpeg2enc was not found. Please install it and try again."; 73 exit 1; 74 } 75 if (&location("mp2enc") eq "") { 76 print "mp2enc was not found. Please install it and try again."; 77 exit 1; 78 } 79 if (&location("mplex") eq "") { 80 print "mplex was not found. Please install it and try again."; 81 exit 1; 82 } 83 if (&location("yuvscaler") eq "") { 84 print "yuvscaler was not found. Please install it and try again."; 85 exit 1; 86 } 87 88 # end init code 89 print "initialised\n"; 90 exit 0; 91 }
Here we see the second directive, init. This is called when the user selects this plugin for output. In this section we can perform any initialisation and checks. If there is an error, we can print out an error message on STDOUT and exit with a code of 1. Otherwise we can exit with a code of 0.
96 if ($command eq "get_capabilities") { 97 # return capabilities - this is a bitmap field 98 # bit 0 - takes extra parameters (using RFX request) 99 # bit 1 - unused 100 # bit 2 - can encode png 101 # bit 3 - not pure perl 102 print "5\n"; 103 exit 0; 104 }
This is the third directive, get_capabilities. Here we print out a flag of the plugin's capabilities on STDOUT, and exit with a code of 0. Bit 0 can be set if the plugin requires extra parameters (this is described below in more detail). Bit 1 is currently unused, bit 2 means the plugin can encode png images as input as well as jpeg, and bit 3 should be set if the plugin is not written in Perl, or if it is a standalone plugin (see above).
In this case, we can encode png images, and we want extra parameters, so we print out "5" and exit with a code of 0.
108 if ($command eq "get_formats") { 109 # for each format: 110 # return format_name|display_name|audio_types|restrictions|extension| 111 112 # audio types are: 0 - cannot encode audio, 1 - can encode using 113 # mp3, 2 - can encode using pcm, 3 - can encode using pcm and mp3 114 115 #mpeg 2 116 print "mpeg2|mpeg2 high quality|4|arate=32000;44100;48000,fps=24000:1001;24;25;30000:10 01;30;50;60000:1001;60,aspect=1:1;4:3;16:9;2.21:1,hblock=8,vblo ck=8|mpg|\n"; 117 118 # mpeg1 may be wrong, aspect (and maybe fps) comes from PAL/NTSC - TODO 119 # needs testing 120 print "mpeg1|mpeg1|4|arate=32000;44100;48000,fps=24000:1001;24;25;300 00:1001;30;50;60000:1001;60,aspect=1:1;4:3;16:9;2.21:1,hblock=8 ,vblock=8|mpg|\n"; 121 122 #vcd 123 print "vcd_pal|vcd (PAL)|4|arate=32000;44100;48000,fps=25,aspect=1:1;4:3;16:9;2.21 :1,hblock=16,vblock=16|mpg|\n"; 124 print "vcd_ntsc|vcd (NTSC)|4|arate=32000;44100;48000,fps=30000:10001,aspect=1:1;4:3 ;16:9;2.21:1,hblock=16,vblock=16|mpg|\n"; 125 126 #svcd
127 print "svcd_pal|svcd (PAL)|4|arate=32000;44100;48000,fps=25,aspect=1:1;4:3;16:9;2.21 :1,hblock=16,vblock=16|mpg|\n"; 128 print "svcd_ntsc|svcd (NTSC)|4|arate=32000;44100;48000,fps=30000:1001,aspect=1:1;4:3; 16:9;2.21:1,hblock=16,vblock=16|mpg|\n"; 129 130 # dvd 131 print "dvd_pal|dvd (PAL)|4|arate=32000;44100;48000,fps=25,aspect=1:1;4:3;16:9;2.21 :1,hblock=16,vblock=16|mpg|\n"; 132 print "dvd_ntsc|dvd (NTSC)|4|arate=32000;44100;48000,fps=30000:1001,aspect=1:1;4:3; 16:9;2.21:1,hblock=16,vblock=16|mpg|\n"; 133 134 # custom 135 print "custom2|custom mpeg2|4|arate=32000;44100;48000,fps=24000:1001;24;25;30000:1001 ;30;50;60000:1001;60,aspect=1:1;4:3;16:9;2.21:1,hblock=8,vblock =8|mpg|\n"; 136 137 exit 0; 138 }
The next directive is get_formats. Here the plugin prints out on STDOUT details of the formats it can handle, their requirements, and exits with a code of 0. Each format contains the following fields: format|description|audio_formats|restrictions|extension and should end with a newline (\n). Format - the short name of the video format, used to identify it Description - user description of the format audio_formats - this is a bitmask of audio formats that the video format can produce, it has currently the following values: bit 1 - mp3 bit 2 - PCM bit 3 - mp2 bit 4 - vorbis bit 5 - ac3 bit 6 - AAC bit 7 - AMR_NB
restrictions - this is a list of restrictions for the video format. The list is separated by semi-colon (;), and can have all, some or none of the following: none - no restrictions arate=x;y;z - limit audio rate (Hz) to x,y, or z fps=a;b:c;d - limit frames per second to a, b:c or d aspect=e:f;g:h - limit (frame) aspect ratio to e:f or g:h hblock=i - width (in pixels) must be a multiple of i vblock=j - height (in pixels) must be a multiple of j size=kxl - frame size is fixed at k pixels width x l pixels height
Obviously, some combinations don't make any sense, for example "none" cannot be combined with anything else; size=100x100 could not be combined with hblock=16. In the case of a contradiction like this, the host action is undefined.
The next directive in our plugin is get_rfx. This is an optional section, which is only called if the plugin sets bit 0 in "get_capabilities". This is explained further on a LiVES forum post: https://sourceforge.net/forum/forum.php?thread_id=1921281&forum_id=777668 This directive also receives the standard parameters. This is explained below in the encode directive. In this section we can print print out an RFX scrap on STDOUT. See the LiVES RFX guide (section 17.3.2) for more details on the format of this scrap. An RFX scrap (as opposed to a full RFX plugin), uses only the following RFX sections: <define>,<language_code>,<params>, and optionally <param_window> and/or <onchange>
The next directive is get_format_request. Here the plugin tells the host
how it would like frames and (optionally) audio presented to it. This is a bitmap flag which the plugin should print out on STDOUT before exiting with a code of 0. The bitmap uses the following bits: bit 0 - if this is unset, the host delivers raw audio, if set, the host will add a wav file header to it bit 1 - if this is unset, the host will deliver all audio, and allow the plugin to clip it itself (because the plugin might be asked to encode only a range of frames and audio), otherwise, audio will be clipped to the section to be encoded. bit 2 - if this is unset, the host will deliver all frames and the plugin will be expected to encode only the frames requested; if it is set, the host will renumber all the frames so that the requested range always starts at frame 1. In our plugin we would have something like: 397 if ($command="get_format_request") { 398 # return the code for how we would like audio and video delivered 399 # this is a bitmap field composed of: 400 # bit 0 - unset=raw pcm audio; set=pcm audio with wav header 401 # bit 1 - unset=all audio; set=clipped audio 402 # bit 2 - unset=all frames; set=frames for selection only 403 404 print "3\n"; # clipped pcm wav, all frames 405 }
However, for non-standalone plugins (see the start of the article), this is implemented as a subroutine which simply returns the value: 397 sub get_format_request { 398 # return the code for how we would like audio and video delivered 399 # this is a bitmap field composed of: 400 # bit 0 - unset=raw pcm audio; set=pcm audio with wav header 401 # bit 1 - unset=all audio; set=clipped audio 402 # bit 2 - unset=all frames; set=frames for selection only 403 404 return 3; # clipped pcm wav, all frames 405 }
The next directive is encode, and here the plugin does the main part of its work. The encode directive is followed by the standard parameters plus any extra parameters which were requested in get_rfx.
For a non-standalone plugin, the LiVES code sets various variables ready for you, for standalone/non-perl plugins, the plugin needs to parse these parameters itself. The variable names are shown here, but for a standalone plugin these would be second parameter, third parameter, etc. (recall that the first parameter is the directive, in this case "encode"). Here are the standard parameters: $fps : the framerate $nfile : the file name to save to, enclosed in quotes $start : the number of the first frame to encode (if "renumbered frames" was requested in "get_format_request", this will always be 1). $end : the number of the last frame to encode $img_ext : the file extension of the image format this is normally .jpg, but if your plugin can handle png, it could also be .png $otype : this is the output (video) format which the user requested, as defined in "get_formats". $atype : this is a number corresponding to the audio type the user requested (see "get_formats") $hsize : the horizontal (width) size of the frames in pixels $vsize : the vertical (height) size of the frames in pixels $DB_ENCODERS : if set to 1, the plugin should provide as much debug output as possible *on STDERR* $arate : the audio rate in Hz (if the plugin or the user requested "no audio", this will be set to 0) $achans : number of audio channels (e.g. 1 for mono, 2 for stereo)
$asamps : audio sample size in bits (e.g. 8 or 16) $ssigned : signedness of audio (1 for signed, 0 for unsigned)
Following these standard parameters are any extra parameters that may have been requested in get_rfx. These parameters start at the 14th parameter for non-standalone plugins, or at the 16th parameter for standalone/non-perl plugins. These extra parameters have strings enclosed in quotes, with any internal quotes escaped as \".
Non-standalone plugins also get some extra variables: $title : title of clip $author : author of clip $comment : comment about clip
The plugin must encode the image sequence and audio (if applicable) which will be present in the current directory, and produce the output file whose name is given. The images are numbered as %8d$img_ext, for example: 00000001.jpg 00000002.jpg etc. The name of the audio file is just "audio" if you requested raw audio. If you requested wav file format, the name will be "audiodump.wav". For non-standalone plugins, the audio file name is set in $audiofile. Note: if the audio rate is 0, you *MUST NOT* encode audio, only video.
named .status (yes, that starts with a ".") in the current directory, and it must contain only the word "completed" (without the quotes). You can then exit with a code of 0. (For non-standalone plugins, you can simply call &sig_complete).
Following encoding, the next directive is clear. This is called by the host after encode. For standalone plugins, the parameters following the directive are the start and end frame numbers. For non-standalone plugins, they are set as $start and $end. Again for this directive, when we are done we need to create a file called .status in the current directory, containing only the word "completed".
if ($command eq "clear") { # this is called after "encode" # note that encoding could have been stopped at any time if (-f $tmpvid) { unlink $tmpvid; } if (-f $tmpaud) { unlink $tmpaud; }
The final directive is finalise. This is called when the plugin is deselected (unloaded) by the user. Here you can clean up any temporary files, etc. 381 if ($command eq "finalise") { 382 # do any finalising code 383
Note: if your encoder wants to create a symbolic link, you should check whether this has worked and if not, copy the file instead. This is because the LiVES working directory may be using a partition which does not support symlinks.
This is the negate effect, which inverts the colours in a video frame. // negate.c // weed plugin // (c) G. Finch (salsaman) 2005 // // released under the GNU GPL 3 or later // see file COPYING or www.gnu.org for details #include "../../libweed/weed.h" #include "../../libweed/weed-effects.h" #include "../../libweed/weed-plugin.h" /////////////////////////////////////////////////////////////////// static int num_versions=1; // number of different weed api versions supported static int api_versions[]={100}; // array of weed api versions supported in plugin, in order of preference (most preferred first) static int package_version=1; // version of this package ////////////////////////////////////////////////////////////////// #include "../../libweed/weed-utils.h" // optional #include "../../libweed/weed-plugin-utils.h" // optional /////////////////////////////////////////////////////////////
all of the above is standard boilerplate int negate_process (weed_plant_t *inst, weed_timecode_t timestamp) {
here we do the actual processing: int error; weed_plant_t *in_channel=weed_get_plantptr_value(inst,"in_channels",&error),*out_channel=weed _get_plantptr_value(inst,"out_channels",&error); unsigned char *src=weed_get_voidptr_value(in_channel,"pixel_data",&error); unsigned char *dst=weed_get_voidptr_value(out_channel,"pixel_data",&error); int width=weed_get_int_value(in_channel,"width",&error)*3; int height=weed_get_int_value(in_channel,"height",&error); int irowstride=weed_get_int_value(in_channel,"rowstrides",&error); int orowstride=weed_get_int_value(out_channel,"rowstrides",&error); unsigned char *end=src+height*irowstride; register int i;
This is our setup function: weed_plant_t *weed_setup (weed_bootstrap_f weed_boot) { weed_plant_t *plugin_info=weed_plugin_info_init(weed_boot,num_versions,api_versions); if (plugin_info!=NULL) { int
palette_list[]={WEED_PALETTE_BGR24,WEED_PALETTE_RGB24,WEED_PALET TE_END}; weed_plant_t *in_chantmpls[]={weed_channel_template_init("in channel 0",0,palette_list),NULL}; weed_plant_t *out_chantmpls[]={weed_channel_template_init("out channel 0",WEED_CHANNEL_CAN_DO_INPLACE,palette_list),NULL}; weed_plant_t *filter_class=weed_filter_class_init("negate","salsaman",1,WEED_FILTER_HINT_IS_ POINT_EFFECT,NULL,&negate_process,NULL,in_chantmpls,out_chantmpls,NULL, NULL); weed_plugin_info_add_filter_class (plugin_info,filter_class); weed_set_int_value(plugin_info,"version",package_version); } return plugin_info; }
Mandatory functions const char *module_check_init(void) Called once when the module is loaded. This should initialise anything needed, and return either an error string or NULL if it succeeds.
int *get_palette_list(void) Returns a list of palettes that the plugin can use, using the Weed palette definitions. Palettes are listed in order of preference and terminated with a WEED_PALETTE_END.
boolean set_palette (int palette) Host calls this to set the current palette.
uint64_t get_capabilities (int palette) Return capabilities for palette. Bitmapped values include:
VPP_CAN_RESIZE : set if the plugin can resize images in the specified palette VPP_CAN_RETURN : set if the plugin alters frames and can return them VPP_LOCAL_DISPLAY : set if plugin displays output on the local screen
These are defined in vidplugin.h boolean render_frame (int hsize, int vsize, int64_t timecode, void **pixel_data, void **return_data) Render one frame. The frame size is hsize (width) * vsize (height) macropixels. Planar data is held in pixel_data. If return_data is non-NULL, the plugin should return altered, resized frames in pixel_data. Timecode is in units of 10 nano-seconds.
The following function is mandatory for local display plugins boolean send_keycodes (keyfunc) The host calls this, passing in a pointer to a key function as the parameter. The function type of keyfunc is: boolean (*keyfunc)(boolean down, uint16_t unicode, uint16_t keymod) For each key in the keyboard buffer, the plugin should call keyfunc, with the following parameters: down should be set to TRUE if it is a keypress, FALSE if a key release unicode is the unicode value of the key keymod is the key modifier, defined in vidplugin.h thus:
MOD_CONTROL_MASK : set this bit if the control key is pressed MOD_ALT_MASK : set this key if the alt key is pressed MOD_NEEDS_TRANSLATION : a plugin specific translation is needed for the unicode value (for example, on key release, incorrect values may be reported).
When there are no more buffered key presses, send_keycodes() should return FALSE. If there are more buffered key presses, return TRUE.
const char *get_rfx (void) Get RFX scrap, run it and return variables in init_screen(). RFX scrap consists of <define>, <language_code>, <params>, <param_window> and <onchange> sections only. See also encoder plugins (section 17.3.3.1).
boolean init_screen (int width, int height, boolean fullscreen, uint32_t window_id, int argc, char **argv) Ready the screen to play. Width and height are the size of the screen area. If fullscreen is TRUE the entire screen should be used, and no window decorations should be shown. If fullscreen is FALSE ans window_id is non-zero, the output should be embedded in window with id window_id. If get_rfx() was defined, argc and argv will hold the parameter values as strings, so for example if the first parameter is an int you would need to use atoi(argv[0]), etc.
void exit_screen (int16_t mouse_x, int16_t mouse_y) Called after playback finishes. Tear down the display and warp the mous pointer to mouse_x, mouse_y.
void module_unload (void) Called when the plugin module is unloaded. Perform any cleanup as necessary (e.g. unlocking hardware).
const char *get_fps_list (int palette) If the plugin can only use discrete fps (frame-rate) values then it can implement this function and return a list when the host calls it. The list returned is a string of format a|b|c where a,b and c would be framerates. Ratio framerates like 24000:1001 are allowed.
boolean set_fps (double fps) If the plugin implements get_fps_list, then it must also implement this function which allows the host to set an fps value. Plugin should return TRUE if the fps value is allowed, otherwise return FALSE.
int *get_yuv_palette_sampling (int palette) Plugin can send a list of palette sampling types, terminated with a -1. Only valid if palette is a YUV palette supported by the plugin. Sampling types are the same as the Weed YUV sampling types. If this function is not implemented, the default sampling type is assumed.
boolean set_yuv_palette_sampling (int sampling_type) If the plugin implemented get_yuv_palette_sampling, the host can choose a sampling type and inform the plugin of this. This will only be called after the host sets the palette.
int *get_yuv_palette_clamping (int palette) Plugin can send a list of palette clamping types, terminated with a -1. Only valid if palette is a YUV palette supported by the plugin. Clamping types are the same as the Weed YUV clamping types. If this function is not implemented, the default clamping type (clamped) is assumed.
boolean set_yuv_palette_clamping (int clamping_type) If the plugin implemented get_yuv_palette_clamping, the host can choose a clamping type and inform the plugin of this. This will only be called after the host sets the palette.
int *get_yuv_palette_subspace (int palette) Plugin can send a list of palette subspace types, terminated with a -1. Only valid if palette is a YUV palette supported by the plugin. Subspace types are the same as the Weed YUV sampling types. If this function is not implemented, the default subspace type (Y'CbCr) is assumed.
boolean set_yuv_palette_subspace (int subspace_type) If the plugin implemented get_yuv_palette_subspace, the host can choose a subsapce type and inform the plugin of this. This will only be called after the host sets the palette.
videoplugin.h also defines TRUE, FALSE, the boolean type, and CPU_BITS.
static SDL_Rect *rect; static SDL_Event event; static SDLMod mod; ////////////////////////////////////////////// const char *module_check_init(void) { if (getenv ("HAVE_SDL")==NULL&&system ("which sdl-config >/dev/null 2>&1")==256) { snprintf (error,256,"\n\nUnable to find sdl-config in your path.\nPlease make sure you have SDL installed correctly to use this plugin.\nYou can override this with 'export HAVE_SDL=1'\n"); return error; } render_fn=&render_frame_unknown; RGBimage=NULL; overlay=NULL; ov_vsize=ov_hsize=0; mypalette=WEED_PALETTE_END; rect=(SDL_Rect *)malloc (sizeof(SDL_Rect)); return NULL; }
const char *version (void) { return plugin_version; } const char *get_description (void) { return "The SDL plugin allows faster playback.\n"; } uint64_t get_capabilities (int palette) { if (palette==WEED_PALETTE_UYVY8888) { return VPP_CAN_RESIZE|VPP_LOCAL_DISPLAY; } return VPP_LOCAL_DISPLAY; } const char *get_rfx (void) { return \"<define>\\n\|1.7\\n\</define>\\n\<language_code>\\n\0xF0\\n\</language_code>\\n\< params> \\n\hwa|Hardware _acceleration|bool|1|0 \\n\yuvd|YUV _direct|bool|1|0 \\n\yuvha|_YUV hardware acceleration|bool|1|0 \\n\dblbuf|_Double buffering|bool|1|0 \\n\hws|Hardware _surface|bool|1|0 \\n\</params> \\n\<param_window> \\n\</param_window> \\n\<onchange> \\n\</onchange> \\n\"; } int *get_palette_list(void) { // return palettes in order of preference, ending with WEED_PALETTE_END palette_list[0]=WEED_PALETTE_UYVY8888; palette_list[1]=WEED_PALETTE_YUYV8888; palette_list[2]=WEED_PALETTE_YVU420P; palette_list[3]=WEED_PALETTE_YUV420P; palette_list[4]=WEED_PALETTE_RGB24; palette_list[5]=WEED_PALETTE_END;
return palette_list; } boolean set_palette (int palette) { if (palette==WEED_PALETTE_RGB24) { render_fn=&render_frame_rgb; mypalette=palette; return TRUE; } else if (palette==WEED_PALETTE_UYVY8888||palette==WEED_PALETTE_YUYV8888||p alette==WEED_PALETTE_YUV420P||palette==WEED_PALETTE_YVU420P) { render_fn=&render_frame_yuv; mypalette=palette; return TRUE; } // invalid palette return FALSE; } int *get_yuv_palette_clamping(int palette) { if (palette==WEED_PALETTE_RGB24) clampings[0]=-1; else { clampings[0]=WEED_YUV_CLAMPING_CLAMPED; clampings[1]=-1; } return clampings; }
boolean init_screen (int width, int height, boolean fullscreen, uint32_t window_id, int argc, char **argv) { // screen size is in RGB pixels int hwaccel=1; int yuvdir=1; int yuvhwa=1; int dblbuf=1; int hws=1; char tmp[32]; uint32_t modeopts=0; if (argc>0) { hwaccel=atoi(argv[0]); yuvdir=atoi(argv[1]); yuvhwa=atoi(argv[2]); dblbuf=atoi(argv[3]); hws=atoi(argv[4]);
} if (mypalette==WEED_PALETTE_END) { fprintf(stderr,"SDL plugin error: No palette was set !\n"); return FALSE; } snprintf(tmp,32,"%d",yuvdir); setenv ("SDL_VIDEO_YUV_DIRECT", tmp, 1); snprintf(tmp,32,"%d",yuvhwa); setenv ("SDL_VIDEO_YUV_HWACCEL", tmp, 1); snprintf(tmp,32,"%u",window_id); if (!fullscreen) setenv ("SDL_WINDOWID", tmp, 1); if ((SDL_Init (SDL_INIT_VIDEO)==-1)) { fprintf (stderr,"SDL player : Could not initialize SDL: %s.\n", SDL_GetError()); return FALSE; } modeopts=(SDL_HWSURFACE*hws)|(SDL_DOUBLEBUF*dblbuf)|(SDL_HWACCEL *hwaccel); SDL_ShowCursor (FALSE); screen = SDL_SetVideoMode (width, height, 24, modeopts | (fullscreen?SDL_FULLSCREEN:0) | SDL_NOFRAME); if ( screen == NULL ) { fprintf (stderr,"SDL player : Couldn't set %dx%dx24 video mode: %s\n", width, height, SDL_GetError()); // do we need SDL_ShowCursor/SDL_quit here ? return FALSE; } /* Enable Unicode translation */ SDL_EnableUNICODE ( 1 ); // if palette is RGB, create RGB surface the same size as the screen if (mypalette==WEED_PALETTE_RGB24) { RGBimage = SDL_CreateRGBSurface(SDL_HWSURFACE, width, height, 24, 0x0000FF, 0x00FF00, 0xFF0000, 0x00); if (RGBimage == NULL) { fprintf(stderr,"SDL player: Can't create: %s\n", SDL_GetError()); return FALSE; } return TRUE; } rect->x=rect->y=0;
rect->h=height; rect->w=width; return TRUE; } boolean render_frame (int hsize, int vsize, int64_t tc, void **pixel_data, void **return_data) { // call the function which was set in set_palette return render_fn (hsize,vsize,pixel_data,return_data); } boolean render_frame_rgb (int hsize, int vsize, void **pixel_data, void **return_data) { // broken - crashes // hsize and vsize are in pixels (n-byte) SDL_LockSurface(RGBimage); memcpy(RGBimage->pixels,pixel_data[0],hsize*vsize*3); SDL_UnlockSurface(RGBimage); SDL_BlitSurface(RGBimage, NULL, screen, NULL); //SDL_FreeSurface(RGBimage); SDL_UpdateRect(screen, 0, 0, 0, 0); return TRUE; } boolean render_frame_yuv (int hsize, int vsize, void **pixel_data, void **return_data) { // hsize may be in uyvy-macropixels (2 real pixels per 4 byte macropixel !) uint32_t ovtype=SDL_IYUV_OVERLAY; if (mypalette==WEED_PALETTE_UYVY8888) { ovtype=SDL_UYVY_OVERLAY; hsize*=2; } else if (mypalette==WEED_PALETTE_YUYV8888) { ovtype=SDL_YUY2_OVERLAY; hsize*=2; } else if (mypalette==WEED_PALETTE_YVU420P) ovtype=SDL_YV12_OVERLAY; if ((ov_hsize!=hsize||ov_vsize!=vsize)&&(overlay!=NULL)) { SDL_FreeYUVOverlay(overlay); overlay=NULL; } if (overlay==NULL) { overlay=SDL_CreateYUVOverlay (hsize, vsize, ovtype, screen); ov_hsize=hsize; ov_vsize=vsize; } SDL_LockYUVOverlay (overlay); if (mypalette==WEED_PALETTE_UYVY||mypalette==WEED_PALETTE_YUYV)
memcpy (overlay->pixels[0],pixel_data[0],hsize*vsize*2); else { memcpy (overlay->pixels[0],pixel_data[0],hsize*vsize); memcpy (overlay->pixels[1],pixel_data[1],hsize*vsize>>2); memcpy (overlay->pixels[2],pixel_data[2],hsize*vsize>>2); } SDL_UnlockYUVOverlay (overlay); SDL_DisplayYUVOverlay (overlay,rect); return TRUE; } boolean render_frame_unknown (int hsize, int vsize, void **pixel_data, void **return_data) { fprintf(stderr,"SDL plugin error: No palette was set !\n"); return FALSE; } void exit_screen (int16_t mouse_x, int16_t mouse_y) { if (mypalette==WEED_PALETTE_RGB24) { if (RGBimage!=NULL) { SDL_FreeSurface (RGBimage); RGBimage=NULL; } } else if (overlay!=NULL) { SDL_FreeYUVOverlay(overlay); overlay=NULL; } if (mouse_x>=0&&mouse_y>=0) { SDL_ShowCursor (TRUE); SDL_WarpMouse ((int16_t)mouse_x, (int16_t)mouse_y); } SDL_Quit(); } void module_unload(void) { free (rect); }
boolean send_keycodes (keyfunc host_key_fn) { // poll for keyboard events, pass them back to the caller // return FALSE if there are no more codes to return uint16_t mod_mask,scancode=0; if (host_key_fn==NULL) return FALSE;
while(SDL_PollEvent (&event)) { mod_mask=0; if (event.type==SDL_KEYDOWN||event.type==SDL_KEYUP) { mod=event.key.keysym.mod; if (mod&KMOD_CTRL) { mod_mask|=MOD_CONTROL_MASK; } if (mod&KMOD_ALT) { mod_mask|=MOD_ALT_MASK; } if (event.type==SDL_KEYDOWN) { if (!mod_mask) { scancode=event.key.keysym.unicode; } if (!scancode) { scancode=(uint16_t)event.key.keysym.scancode; mod_mask|=MOD_NEEDS_TRANSLATION; } host_key_fn (TRUE,scancode,mod_mask); } else { // key up - no unicode :-( host_key_fn (FALSE,(uint16_t)event.key.keysym.scancode,(mod_mas k|MOD_NEEDS_TRANSLATION)); } } } return TRUE; }
Mandatory functions
const char *module_check_init(void) This function is called once, when the host loads the module. The plugin should do any setup activities here. The return value is an error string, or NULL if no errors occurred.
const lives_clip_data_t *get_clip_data(char *URI) Given a URI, (generally a filename), parse it and return clip data. lives_clip_data_t is defined below.
boolean get_frame(char *URI, int64_t frame, void **pixel_data) Get frame number frame from URI (normally a filename), and return the results in planes pixel_data. Return FALSE if an error occurs, return TRUE on success.
Optional functions
boolean rip_audio (char *URI, char *fname, int stframe, int frames) If the decoder is capable of decoding audio, it can provide this function. Audio starting at frame stframe, with a length of frames from URI (usually a filename) should be decoded and written to file fname. If frames is 0, then rip all available audio.
boolean set_palette(int palette) If the plugin provided a choice of palettes for decoding to, it must provide this function so that the host can select a palette to use. It should return TRUE if the palette was set correctly, FALSE otherwise. When this is called, the plugin should alter its const clip_data accordingly.
void module_unload(void) This function can be used to do anything necessary when the module is unloaded, for example releasing hardware.
lives_clip_data_t
The following structure is defined in decplugin.h and a pointer to one of these must be returned by the function get_clip_data(). This struct should be maintained by the plugin, and if the host calls set_palette(), the values may be updated.
int width; // width in macropixels, may change if palette is set int height; int nframes; int interlace; // see below int YUV_sampling; // as defined in weed-effects.h, may change if palette is set int YUV_clamping; // as defined in weed-effects.h, may change if palette is set int YUV_subspace; // as defined in weed-effects.h, may change if palette is set float fps; int *palettes; // list of palettes that the plugin can return frames in, format is as used in weedeffects.h // in order of preference, terminated with WEED_PALETTE_END. // if more than one palette, host can set a choice by calling set_palette() // plugin should then update width, sampling, clamping and subspace as appropriate char container_name[512]; // name of container, e.g. "ogg" or NULL char video_name[512]; // name of video codec, e.g. "theora" or NULL char audio_name[512]; // name of audio codec, e.g. "vorbis" or NULL int arate; int achans; int asamps; // audio sample size in bits int asigned; // 0 = unsigned, 1 = signed int ainterleaf; // 0 = non-interleaved, 1 = interleaved
Interlace types are defined as: #define LIVES_INTERLACE_NONE 0 #define LIVES_INTERLACE_BOTTOM_FIRST 1 #define LIVES_INTERLACE_TOP_FIRST 2 #define LIVES_INTERLACE_PROGRESSIVE 3 The header decplugin.h defines TRUE, FALSE, the boolean type, lives_clip_data_t, and interlace types.
<tmpdir> is the LiVES temporary directory. <setname> is the name of the set.
Project format:
a copy of the complete set, tarred and gzipped. The file extension is normally then set to .lv2.
18 Toys