Embed Size (px)
Citation preview
LiVES manual
Publication date 2009-08-25
http://lives.sourceforge.net
© Gabriel Finch ([email protected])
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 non-propertarian 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, One Nation"
- Public Enemy 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 que con el tiempo mereceremos no tener gobiernos." - Jorge Luis Borges, 1899-1986 Naturally our cartography draws connections among nodes, hubs of intelligence that are closer in cyber space than in the physical one. In the last century we have learned how we can share music, lyrics, stories and images, since for a few decades we are able to copy them with marginal costs across the whole world. This let us relate to each other with an outreach that is amplified by the density of our living environments, the urban spaces that somehow offered enough gaps for our agency. Those who pretend to govern our living are now busy in controlling those voids, as every tree in a public square represents an obstacle for their cameras, omnipresent eyes patronising our evolution. We found shelter in the ancestral practices of trance[4], opening the doors of our perception to the unknown, resonating our own bones, enhancing the agility of our tongues to follow the hip hop flow of radical thoughts, skating over the universe we are constrained, painting fantasy over the imposed walls of our cities, jumping higher to join the loose ends of our parkours. These practices are now among all of our cities[5], seeded by our own need to evolve, to influence a governance that doesn't listen to us. Some kids turn into a dark army of vengeance, some lose faith in the future, some fall in the virtual loopholes offered by the magnetic startups of the dot.com boom. We need to offerourselves an alternative to this hopeless conflict and the first step is to build a narrative that respects all choices, that doesn't neglect suffering. All this creativity and despair is shared among our cities, stuffed by unnecessary needs and mirages of success of the "creative industries", while we already elaborate a concentric vision that is linked to the density of our lives and the cultural flow of our errant knowledge. Therefore we declare the birth of a **planet of networked cities**[6], spiral architectures of living swirling above our heads and across our fingers, as they
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: 010-Publishers [6] Batten, D.F. (1995), Network Cities: Creative Urban Agglomerations for the 21st Century, SAGE [7] Lapassade, G. (1971), L'Autogestion pédagogique, 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 controls the media -the images- controls the 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 Introduction to the LiVES Project and the LiVES application
LIVES is a free software project. The aim of the project is to promote free and open standards in multimedia, and to provide access to them to as many people as possible. Part of this project involves the development of a software application (from which the project takes its name: LiVES is a Video Editing System). Another part of the project consists of helping to develop and promote free standards in multimedia. This manual is about LiVES, the application. The project and software were started in 2002 by Gabriel Finch (a.k.a salsaman, VJ salsa) and he is still the main developer of the project.
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 Getting support
1.2.1 Bugs and feature requests
Bug reports are very welcome. You can report a new bug at: http://sourceforge.net/tracker/?group_id=64341&atid=507139 You can also check there to see if a bug has been reported already. There is also a place for feature requests: http://sourceforge.net/tracker/?group_id=64341&atid=507142
1.2.2 Mailing lists
There are two mailing lists for LiVES: for end user related matters there is the lives-user mailing list. For more technical (development related) issues, there is the lives-devel mailing list. These lists are generally low volume - more or less 3 or 4 messages per week, although this should increase as more people discover the joys of LiVES ! https://lists.sourceforge.net/lists/listinfo/lives-users - lives user mailing list https://lists.sourceforge.net/lists/listinfo/lives-devel - lives development mailing list
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
Discussion of the remote interface / OSC / streaming
And a couple of more advanced topics:
Video Editing
VJing with LiVES
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.
1.2.5 RSS 2.0 news feed
There is an RSS 2.0 news feed for LiVES. You can subscribe to this by clicking on the RSS icon on the LiVES site, or with the URL: http://lives.sourceforge.net/content/news.xml
2 Compiling and installation
2.1 Obtaining the sourcecode
The sourcecode for the latest LiVES release can always be obtained by following the links on: http://lives.sourceforge.net/index.php?do=downloads 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.
Checking out the code
Decide which version you would like to download, development or stable.
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)
2.4 Binary locations
Binary versions of LiVES can be obtained from various sources depending on the distribution. 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.
Ubuntu
Ubuntu packages can be downloaded from http://www.getdeb.net Slackware
Slackware has some nice LiVES packages at slacky.eu Gentoo emerge lives Arch linux http://aur.archlinux.org/packages.php?ID=1642 Fedora, Mandriva and SuSE and have packages on sourceforge:
http://sourceforge.net/project/showfiles.php?group_id=64341
For other distributions you may find a search engine useful... For BSD
http://www.freshports.org/multimedia/lives/
http://www.freebsdsoftware.org/multimedia/lives.html
2.5 Compiling from source
If you got LiVES as a tar.gz or tar.bz2, at a terminal prompt, enter the following: bzip2 -d LiVES-<version>.tar.bz2
or, gzip -d LiVES-<version>.tar.gz
depending on which version you have. Then: tar xvf LIVES-<version>.tar
cd lives-<version>
Replace <version> with the version of LiVES which you downloaded; for example 0.9.9.6 or 1.0.3 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 For a complete list of configure options, type:
./configure --help
2.6 dyne:LiVES CD/pendrive
Windows and Mac (Intel) users can try out LiVES by downloading and burning a dyne:bolic bootable CD, and then installing the LiVES module. This is based on the wonderful dynebolic distribution: http://www.dynebolic.org/ Instructions: 1) Download the latest dynebolic (currently 2.5.2) ISO and burn it to a CD with your favourite CD burning software. Make sure you burn the .iso image as-is. This will create a bootable CD. 2) Boot from the CD and create a "dock" (i.e. copy the /dyne directory from the CD to a harddrive). You can also create a "nest" (/home directory) if you wish. 3) Download the latest dyne:LiVES module: http://lives.sourceforge.net/LiVES-latest.dyne and copy it into /dyne/modules on the "dock" harddrive. 4) Reboot once more from the CD, and when prompted, select "boot from harddisk" 5) LiVES should now appear in the menu under Video/Edit
2.7 Initial Setup (temporary directory, audio player, theme, etc.)
On the first startup of LiVES (or if the .lives file is not present in the home directory), you will be prompted to select the initial audio player.
Fig 2.7.1 – selecting an initial audio player
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,
Fig. 2.7.2 – selecting the audio player in Preferences
Here you can also select mplayer as the audio player. This is not recommended, but
you can experiment with this if you wish.
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
be in a partition with plenty of disk space (at least 10 GB of space is recommended,
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.
Fig 2.7.3 – output of “df”
Fig 2.7.4 – Directory Preferences
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.
Fig 2.7.5 – Warning when changing the temp directory
You can choose the appearance of Lives.
Fig 2.7.6 – setting a new theme 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).
2.8 Multi-head support
When LiVES is started, it should detect the number of monitors connected, and adjust itself accordingly. In preferences, you can override the default settings. It is possible to choose which monitor to use for the main interface, and for the playback window. You can also set it so that full screen playback will stretch across all monitors (to do so, set the GUI monitor setting to 0). You can also force single monitor mode. This is useful in the rare occasions when the number of monitors is not detected correctly, or if there is some problem with the second screen.
Fig 2.8.1 – Multi-head settings in Preferences
Tip: You may wish to return to this setting once you have experimented with separate window and full-screen playback modes.
3 Running LiVES
3.1 Command line options, and setting the language
Running LiVES from a commandline / terminal is as simple as typing: lives
Tip: lives is generally a symbolic link to the actual binary which is called (for historic reasons) lives-exe. You can also create lives as a wrapper script, which for example, sets environment variables before calling lives-exe. 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
Before starting LiVES as usual with: lives
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.
3.2 From a menu
Starting LiVES from a menu is very much simpler, but generally less flexible. Simply locate the menu entry for LiVES (generally in multimedia/video/edit type menus), and click on the LiVES entry.
4 The clip editor
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.
Fig 4.1.1 – the Clip Editor
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.
4.2 Importing and capturing
4.2.1 Importing clips (single and multiple)
The most common way of importing video and audio material, is via the menu option File -> Open file / directory, or by pressing ctrl-o. If you click on this or press the keys, a file selector will appear, which will allow you to select a file to open (import).
Fig 4.2.1 – the media file selector 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:
Fig 4.2.2 – the 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.
4.2.2 Importing images (single and multiple)
This is done from the same menu option above, File -> Open file or directory. Images are imported just like video clips. They can also be previewed by selecting them and then clicking on Preview in the file selector. If you choose to open a directory, LiVES will import all images in that directory, in alphanumerical order. In this way you can open for example animations or renderings.
Tip: You can choose whether single images are opened as separate files or are to be collated together into one clip. This can be set in preferences. This only makes sense when you select multiple files to open.
4.2.3 Importing audio
This can also be done from the menu option File -> Open file / directory. Click on an audio file to select it. You can preview it in the file selector. Multiple audio files in the same directory can be opened by pressing shift or ctrl, and clicking on the files wanted. The preview, enough and cancel buttons also work with audio. By default, LiVES supports importing audio in the following formats: ogg vorbis, mp3, wav, mod, it, xm.
4.2.4 Importing parts of clips
Importing part of a video clip can be done from the menu File -> Open file selection. Here you can choose a video clip as in section 4.2.1. After selecting the clip, a second window appears, which allows selection of the start time in seconds, and the maximum number of frames to import.
Fig 4.2.2.1 – opening part of a video clip 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.
4.2.5 Importing from a remote location (URL)
In LiVES, you can also import video or audio material from a remote location (URL), which could be a file on another server, or could be a stream. You can do this using the menu option File -> Open location/stream or by pressing ctrl-l.
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.
4.2.6 Importing from DVD/VCD
LiVES has the ability to import material from DVD or VCD (video CD format), provided these capabilities are in your copy of mplayer. To import from a DVD:
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. To import from a VCD:
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.
4.2.7 Importing from DV / HDV
In LiVES, you can import material from a dv or hdv camera. In order for this option to be present, LiVES must have been compiled with libdv support. Assuming that is the case, you will also need to have the program dvgrab present for importing from dv to be available. If all required components are present, you can go to the menu option File -> Import from device Here you should see further options: Import from firewire device (dv) and Import from firewire device (hdv) Connect your camera, and then select the appropriate menu option. If all is well, a window with shuttle controls will open
Fig 4.2.7.1 – camera shuttle and grab controls
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.
4.2.8 Capturing an external window
Video (and optionally audio) material can also be captured from external windows on the same desktop. To do so, you can go to the menu option: Tools -> Capture External Window A window will appear where you can set your record preferences - the frame rate, and the maximum record time (or unlimited).
Fig 4.2.8.1 – settings before recording an external window
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.
4.3 Switching clips
Each time a new clip is opened, it is added to the Clips menu. Using this menu, you can switch from one clip to another. The currently selected clip is known as the Current Clip, and is indicated by:
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
4.4 Show clip info
The menu option Info -> Show clip info, shows various details about the current clip.
Fig 4.4.1 – Clip Info
The following information is shown: Video (if clip has video):
Format (original, if known)
Frame size (width x height in pixels)
File size (in MB, if known)
FPS (frames per second)
Frames (total number of video frames)
Total time (video - in seconds)
Audio (if clip has audio): - for each channel:
Rate/size (in Hz and in bits)
Total time (audio channel - in seconds)
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.5 Renaming a clip in the menu
You can rename any clip in the Clips menu. This is simply to make it easier to identify a clip when selecting it, and has no other effects. To rename a clip in the menu, first make it the Current Clip by selecting it [see section 4.3]. then select Clips -> Rename Current Clip in Menu now enter the new name for the clip, as you would like it to appear in the clips menu, for example "main", "background clip", "loop123", then click OK.
4.6 Closing a clip
You can also close a single clip by switching to it, then using menu option File -> Close This Clip. If the clip has changed since it was last encoded, saved or backed up, then a window will appear informing you of this, and asking if you are sure you want to close. You can close all clips via the Menu option File -> Close/Save all clips. In this case you will have the opportunity to save all clips as a Set [see section 4.7.2] before closing them.
4.7 Sets
4.7.1 Introduction to Sets
A Set in LiVES is simply a group of clips. Every time you import one or more clips in LiVES, you either create a Set or add to an existing Set. A Set can be saved and then reloaded instantly - in this case, the Set is left on the hard drive until you choose to delete it. Sets can be merged together. A set also forms the major part of a project (along with its layouts - see section 4.8 and section 11.25). The only limit to how many sets you can have on one machine is the disk space required. However, (currently) only one set can be open at any one time in LiVES. Sets are also locked when in use, so that only one copy of LiVES can access a set at any instant in time.
4.7.2 Saving a Set
There are two ways to save a Set in LiVES.
Via the menu option File -> Close/Save all clips
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.
Fig 4.7.2.1 – Close/Save all clips
When exiting LiVES with open clips.
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.
Fig 4.7.2.2 – prompt when exiting LiVES with open clips 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.7.3 Reloading a Set, autoreloading
There are various ways of reloading a Set – for example it can be auto-reloaded when LiVES is started up (if you selected this option when the Set was saved), you can use the menu option: File -> Reload clip set, and enter the name of a Set which you would like to reload, or you can pass the startup option lives -set <setname> (see section 3.1). When clips from a Set are loaded, LiVES will put the name of the set in brackets at the end of the filename (in the Clips menu and elsewhere). Any existing clips are added to the set when a set is opened. After opening a Set you can continue as normal opening more clips. Any newly opened clips will be automatically added to the Set when you come to save it again. However, once you have opened a set, you will not be able to open a second set without closing or deleting the first one. If you want to merge two sets, you will need to save both sets with the same name [see section 4.7.2].
Tip: there is a perl script called set_shuffle.pl, which can be found in the tools directory shipped with LiVES. Running this script and providing a set name will cause the order of clips in that set to be randomly shuffled. Vjs may like to use this to provide an elemnet of randomness to their sets.
4.7.4 Deleting a Set
In order to delete a Set in LiVES, you must first load it. So if you have other clips loaded you need to close them (possibly saving them as a set - see section 4.7.2); then load the clip Set which you want to delete. To delete the current clip Set, either select the menu option File -> Close/Save all clips, and choose the option to delete the clip Set, or alternately, quit from LiVES (menu option File -> Quit) and choose the option to delete the clip Set here.
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). Projects can be used in various ways, for example:
to back up a Set, so that it can be archived and deleted, then retrieved later as necessary
to copy a Set from one machine to another
4.8.1 Exporting a project
To export a project, select the menu option File -> Export project (.lv2) Enter the filename of a the file to be used to contain the project. It is recommended that you leave the file extension as the default (.lv2). Note: if any files are opened in File mode (see section 4.1), the original files will need to be copied separately.
4.8.2 Importing a project
You can only import a project if there are no clips open. So you may need to close or save all your current clips, or restart LiVES with no clips. A project can be imported via the menu option File -> Import project (.lv2), then select the file to import from.
4.9 Encoding
4.9.1 Encoding a clip
Encoding the current clip can be done from the menu option File -> Encode clip as (or File -> Encode clip, to re-encode using the existing settings). After selecting the menu option File -> Encode clip as, a file selector appears to allow selection of the file name. Here you can choose the location to save (encode) the clip to, as well as whether to allow LiVES to set the file extension. Since the file extension varies depending on the video codec used, it is best to let LiVES set this, unless there is some specific reason to override the default. After picking the file name and location and extension option, click OK. Now you can choose the Target Encoder. Lives has several encoders, each has different formats available.
Tip: It is also possible to set the target encoder from Preferences, or when rendering a clip.
Fig 4.9.1.1 – Encoder details window
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:
Several mpeg formats (mpeg1, mpeg2, DVD compatible)
flv (flash) format
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
swf (flash) format
pdf format (each frame becomes a page in a book)
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.
4.9.2 Encoding a selection
It is also possible in LiVES to encode just part of the current clip. To do this, select the frames which you would like to encode (see section 4.11.1). Then choose menu option File -> Encode selection as. The options are exactly the same as for encoding an entire clip. Before encoding, LiVES will make a temporary copy of the selected frames. The copied frames will be resized/resampled as appropriate. After encoding, the temporary copy will be removed.
4.9.3 Encoding with/without audio
By default, both video and audio for a clip are encoded. Audio is trimmed or padded with silence to fit the length of video. However, some codecs do not allow audio (for example, animated gif). For other codecs, it is possible to force encoding without audio. This is done by deselecting Encode/Load/Backup with sound, from the File menu, before encoding the clip or part of the clip.
4.10 Playing clips
4.10.1 Starting and stopping playback
Playback of the current clip video and/or audio can be started in various ways:
via menu option Play -> Play all (or in the multitrack window, Play -> Play from timeline position), or
by pressing the "p" key when nothing is playing, or
by clicking on the Play All icon in the toolbar, or
by clicking on the Play All button in the separate window [see section 4.10.4]
Fig 4.10.1.1 – toolbar play button
it can be stopped by:
the end of the video or audio is reached, and loop continuous is not set [see section 4.10.7]
via the menu option Play -> Stop
by pressing the "q" key when a clip is playing
by clicking on the stop icon in the toolbar
by clicking on the stop button in the separate window [see section 4.10.4]
Fig 4.10.1.2 – toolbar stop button
4.10.2 Playing a selection
It is possible to play only the currently selected frames of the current clip. This can be done by any of the following:
via menu option Play -> Play selection, or
by pressing the "y" key when nothing is playing, or
by clicking on the Play Selection icon in the toolbar, or
by clicking on the Play Selection button in the separate window [see section 4.10.4]
Fig 4.10.2.1 – toolbar play selection button
Note: This function is not currently available in multitrack mode.
4.10.3 The playback pointer
The playback pointer shows the position where playback will begin, and it appears as a line in the timeline.
Fig. 4.10.3.1 – position of the playback pointer in the Clip Editor
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:
via menu option Play -> Rewind, or
by pressing the "w" key, or
clicking the Rewind icon on the toolbar, or
using the Rewind button in the separate window [see section 4.10.4]
Fig 4.10.3.2 – the rewind button on the toolbar in Clip Editor
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.
4.10.4 The separate window
LiVES provides a choice of playback, either embedded in the LiVES interface, or in a separate window. The separate window can also be used to select start and end frames when editing a clip [see section 4.11.1]
Fig 4.10.4.1 – the separate playback window
To activate the separate window, you can do any of the following:
activate the menu option Play -> Play in separate window, or
press the "s" key, or
click once on the Separate Window icon in the toolbar
Fig 4.10.4.1 – the separate window button on the toolbar To deactivate the separate window, you can do any of the following:
deactivate the menu option Play -> Play in separate window, or
press the "s" key, or
click once on the Separate Window icon in the toolbar, or
click on the close icon in the separate window
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]
4.10.5 Full-screen mode
In full-screen mode, playback occupies the whole monitor (or one or more monitors in multi-head mode). Full-screen playback can be internal, in which case the LiVES interface is still visible, or it can be in the separate play window [see section 4.10.4], in which case the whole of the screen is devoted to video playback (except for some playback plugins - see section 4.10.6)
Tip: In multi-head mode, full-screen/separate window playback can use one of the monitors, or it can be stretched over all monitors. You can select this in Preferences -> GUI, by entering your choice for the playback monitor. A value of 0 means that full-screen playback will stretch over all monitors. Full-screen, separate window mode is known as fs mode, and currently this is the only mode which will trigger playback plugins [see section 4.10.6]. You can enter full-screen mode in one of the following ways:
activate the menu option Play -> Fullscreen, or
press the "f" key
To deactivate full-screen mode, you can do any of the following:
deactivate the menu option Play -> Fullscreen, or
press the "f" key
4.10.6 Playback plugins
LiVES has a variety of playback plugins (both for video and for audio), and depending on the way it was compiled some or all of these may be available for use. To use a playback plugin, either:
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.
Fig 4.10.6.1 – playback plugin advisory
Some examples of audio playback plugins:
jack : the recommended audio plugin, if your hardware will support it
sox : the fallback plugin if sox will not work
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.
4.10.7 Loop modes
LiVES can play back video and audio material using a variety of looping methods. The default mode is Loop video to fit audio. This means that video in a clip will loop until the audio for that clip or selection ends. This mode can be deselected from the Play menu, or by pressing the "l" key during playback (jack audio player only). 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).
Fig 4.10.7.1 – loop mode button on the toolbar
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.
4.10.8 Fade mode, double size
There are a couple of other less frequently used playback options in LiVES: fade mode and double size. These modes are only available in the Clip Editor. When fade mode is activated, most of the LiVES background disappears (is blanked out), just leaving the playback window. This is sometimes nice for displays, particularly when combined with double size. To enter fade mode:
select the menu option Play -> Blank background, or
press the "b" key once during playback
To leave fade mode:
deselect the menu option Play -> Blank background, or
press the "b" key once during playback
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:
deselect the menu option Play -> Show frame counter, or
press the "h" key once during playback
to show the frame counter again:
select the menu option Play -> Show frame counter, or
press the "h" key once during playback
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:
select the menu option Play -> Double Size, or
press the "d" key once during playback
To leave double size mode:
deselect the menu option Play -> Double Size, or
press the "d" key once during playback
4.10.9 Mute mode and volume adjustment
It is also possible to play back video without audio; this is known as Mute Mode. With the jack audio player, you can enter and leave mute mode at any time, including when LIVES is playing; with sox, you can enter and leave mute mode only when LIVES is not playing. To enter mute mode:
select the menu option Play -> Mute
press the "z" key once during playback (jack audio player only), or
click once on the Mute Audio icon in the toolbar, or
click on the Mute Audio icon in the separate window (clip editor mode only)
Fig. 4.10.9.1 – mute button on the toolbar
To leave mute mode:
deselect the menu option Play -> Mute
press the "z" key once during playback (jack audio player only), or
click once on the Mute Audio icon in the toolbar, 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.
Fig 4.10.9.2 – volume slider on the toolbar
4.11 Editing clips
4.11.1 Selecting frames
Each clip in the clip editor has what is known as a Selection. The selection runs continuously from the start frame to the end frame. The largest selection is from frame 1 (the first frame) to the final frame of the clip, and the smallest selection is a single frame. Clips that are audio only may not have a selection.
Fig. 4.11.1.1 – start and end spinbuttons for the selection 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.
4.11.3 The clipboard
The clipboard is used for Paste, Insert and Merge operations as explained below. The clipboard is initially empty, until frames are placed into it, by using either Copy or Cut. 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.
4.11.8 Decoupling video and audio
By default, Delete, Copy and Cut are applied only to the video in a clip. If you would like these options to apply to audio for the selection as well, this can be achieved by deselecting Decouple Video from Audio, in the Edit menu.
Tip: there is a trick you can do if you want to insert just audio. First copy the frames with Decouple Video from Audio deselected. Insert video and audio into the target clip. Then select Decouple Video from Audio, and click on Edit -> Undo Insert. Because Decouple Video from Audio is selected, only the insert of video will be undone, leaving just the audio inserted.
4.11.9 Select last insertion
If frames have been inserted into a clip, then they can be easily selected, using the menu option Edit -> Select -> Select Last Insertion/Merge
4.11.10 Saving single frames
Single frames from the current clip can be saved quite easily. Simply right click on the frame image in either the start frame, the end frame, or in the separate window. A file selection window will open so you can navigate to and enter the name of a file to save the image to. Enter the name of the file to save the image to (including the file extension) and the frame image will be saved. The image format is determined by the file extension, e.g.: .jpg = jpeg format .png = png format .bmp = bitmap format .gif = gif format 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:
use the menu option Edit -> Undo...
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. Many operations can subsequently be redone after an undo. To redo an operation:
use the menu option Edit -> Redo...
or press ctrl-z
4.12 Rendered 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.
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.
4.12.2 Merging between clips
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.
Fig. 4.12.2.1 – the Merge window
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,
as shown in the diagram below
Fig 4.12.2.2 – merge alignment
If the (resampled) clipboard contains more frames than the selection, you will also have two options for how to handle the extra frames:
drop the extra frames
insert them
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.
4.12.3 Select last effect/merge
After a merge, it is possible to select both the merged area and the area of any insertion & merge. Edit -> Select -> Select Last Effect : selects the merged area Edit -> Select -> Select Last Insertion/Merge : selects the merged area, plus any frames which were inserted with the merge
4.12.4 Locking the selection width
Sometimes, it is useful to be able to lock the selection width. For example, you might want to apply various effects to each block of 100 frames. To lock the selection width, select the menu option Edit -> Lock Selection Width. Once the selection width is locked, the following effects will occur:
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.
4.12.5 Rendered generators
LiVES can render frames from a variety of rendered generators. The sub-menu Tools -> Generate, can be used to show a list of these generators. Click on the desired generator and you will see a window for the generator. Here you can choose whether to render to a new clip, or whether to render into the clipboard. The generator itself will also have some settings, at the very least the number of frames to be generated and the frame size. You can get a preview of the results by clicking on the Preview button. When you are happy with all of the settings, click OK - otherwise click Cancel. As the frames are being generated you will be offered the standard options of Preview, Pause and Cancel. If you Pause the processing then you can Preview, Resume processing, or Keep the frames which have been generated and stop generating more. Otherwise, simply wait, and the requested number of frames should be generated.
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).
4.12.6 Installing custom effects, tools and utilities
On the LiVES website you can find various custom effects. Many of these require optional external components (libraries or binaries), and are thus not included in the core LiVES package. The add-ons URL is: http://lives.sourceforge.net/index.php?do=addons Please read the description of each effect before downloading it, to make sure you have all of the pre-requisites installed if you intend using it. Then simply right click on the script (make sure you select the correct version to match your version of LiVES). Save the .script file. Then in LiVES go to the menu option Advanced -> RFX Effects/Tools/Utilities -> Import Custom RFX Script. Locate the script file which was downloaded and click OK. LiVES will automatically regenerate the menus and you should see the imported effect appear in the correct location:
for custom effects, in the Effects -> Custom Effects menu
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).
5.3 Trimming and adding a border
Another tool in the Clip Editor will allow you to trim down a frame, reducing its size and visible area, and optionally add a frame border. To select this tool, click on Tools -> Trim Frames/Add border. 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.
5.5 Changing the playback speed
Changing the playback speed allows for a clip to be sped up or slowed down, and there is a tool to enable you to do this. As opposed to resampling, this will change the duration of the clip. 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.
Fig. 5.5.1 – the Change Speed tool
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.
5.6 Reverse clipboard
The Reverse clipboard tool will reverse the order of video frames in the clipboard. This can be
used for example to create a looping video:
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]
Note: only video is reversed, audio is not reversed.
6 Audio in clips
In this section, we will look at some of the functions for dealing with audio in the Clip Editor.
6.1 Deleting audio
The audio can be deleted from an entire clip or just from the selected part of the current clip. These options are only available for clips with audio. To delete all audio from the current clip, use the menu option Audio -> Delete Audio -> Delete All Audio. To delete part of the audio from the current clip, select the video frames corresponding to the audio to be removed [see section 4.11.1], then use the menu option Audio -> Delete Audio -> Delete Selected Audio. The audio deletion can be undone using the menu option Edit -> Undo Delete Audio.
6.2 Opening new audio
If the current clip has no audio, or you want to replace the audio of the current clip, then you can make use of the menu option Audio -> Load New Audio for Clip. You can import audio of type ogg vorbis, mp3, .it, mod, .xm and wav, provided you have the correct programs/libraries installed (mpg123, mpg321 or mplayer for mp3; ogg123 or mplayer for ogg vorbis, mplayer for .it, mod and xm). Once you have selected the audio file to be loaded, click OK. The audio will replace the current audio for the clip. 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.
6.3 Appending audio
The Clip Editor has a tool for appending audio to the end of an existing audio track. The choice of audio formats is the same as for opening audio [section 6.2]. Select the menu option Audio -> Append Audio, and choose the audio file which you would like to append. This option is only available for clips with existing audio. Appending audio can be undone using the menu option Edit -> Undo Append Audio.
6.4 Trimming/padding audio
You can trim or pad audio to fit a given selection of frames. If the audio track is longer than the video selection, the end is chopped off to fit the selection. If shorter, the audio is padded to the end of the selection with silence. The part of the audio before the selection is filled or replaced with silence. Generally you would select all frames before using this, in order to trim or pad the audio to be of equal length to the video. You can activate this tool with Audio -> Trim/Pad Audio -> Trim/Pad Audio to Selection. You can also trim or pad audio up to the position of play start [see section 4.10.3]. After positioning the play pointer, select the menu option Audio -> Trim/Pad Audio -> Trim/Pad Audio to Play Start. These options are only available for clips with audio. The operation can be undone using the menu option Edit -> Undo Trim/Pad Audio.
6.5 Inserting silence
Yet another audio tool in the Clip Editor will allow you to insert silence in the selected area. If the existing audio is shorter than the selection start, it will be padded with silence up to the selection start frame. The area in the selection will then either be filled or replaced with silence. You can activate this audio tool with the menu option Audio -> Insert Silence in Selection. If the clip has no existing audio, you will be prompted to enter audio details: rate, number of channels, sample size, signedness and endianness. Usually you can simply accept the default suggestion.
Fig. 6.5.1 – setting values for new audio The operation can be undone using the menu option Edit -> Undo Insert Silence.
6.6 Exporting audio
You can save all or part of the audio track(s) from the current clip as a .wav file. To save all of the audio, use the menu option Audio -> Export Audio -> Export All Audio. To save part of the audio, first select the part which you would like to export [see section 4.11.1]. Then click on the menu option Audio -> Export Audio -> Export Selected Audio. Select the file you would like to save the audio to and click OK. These options are only available for clips with audio.
6.7 Fade in/fade out
The Clip Editor has a tool which will let you fade audio in or out, either over the selected frames, or by time. To fade audio in:
Click on the menu option Audio -> Fade Audio In
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.
To fade audio out:
Click on the menu option Audio -> Fade Audio Out
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.
Fig. 6.7.1 – fading audio in and out
6.8 Recording audio for part of a clip or whole clip
If you are using the Jack plugin for audio, you can record audio with external microphone. You can record new audio for selected video frames, or you can record audio to a new clip. To record new audio for a selection:
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
Fig. 6.8.1 – audio recording settings
To record audio to a new clip:
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.
6.9 Resampling audio
In the Clip Editor there is a tool to resample audio. Advanced users may wish to use this, for example to reduce the file size before encoding for a website, you may wish to reduce the Hz, convert from stereo to mono, and reduce from 16 bit samples to 8 bit samples. When combined with a down-sampling of video frame-rate, this can be a powerful tool to reduce the eventual encoded size. Similarly this would reduce the bit rate for streaming. Another reason for resampling might be if you loaded a clip with low quality audio, but you wanted to append insert or mix with higher quality audio. In this case you would up-sample and increase the sample size from 8 bit to 16 bit, say, before doing the append, insert or mixing. To resample the audio, use the menu option Audio -> Resample Audio.
Fig. 6.9.1 – resampling audio Here you can adjust any of the following:
the audio rate
the number of channels
the sample size in bits
signed/unsigned
endianness (big endian or little endian)
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.
7.1 Mapping of keys, enabling, disabling
To use a realtime effect during playback in LiVES, the effect must be mapped to a key and a mode. To assist with this, LiVES has a key mapping tool, which can be activated using the menu option VJ -> Real Time Effect Mapping, or by pressing the key combination ctrl-v. This causes the realtime effects window (hereafter referred to as the RTE window) to open.
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.
Fig. 7.1.2 – some of the modes for effect key ctrl-1 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].
Fig. 7.1.3 – mapping an effect to an effect key and a mode
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).
7.2 Keyboard grab/effect mode
In section 7.1, we saw that each effect key has a number of modes (by default 8) and that only one mode can be active for a key at any instant. There are various ways to change the mode of a key, but first we must look at a concept called the keyboard grab. Keyboard grab is activated by pressing the "k" key, and it will attach various keys on the keyboard to the last enabled effect key. For example, if you press ctrl-1 to switch on the effect on that key, and then press "k", the keyboard is grabbed for the effect key ctrl-1. If you then press ctrl-2 and "k", the keyboard is grabbed for effect key ctrl-2. Pressing ctrl-1 again followed by "k" will not affect the keyboard grab, since the ctrl-1 key-press will disable the effect bound to ctrl-1, and only enabling an effect counts. If you have the RTE window open (see section 7.1), then you can also set the keyboard grab by clicking in the check box labelled "Key grab" near each effect key. When the keyboard is grabbed for an effect key, the following keys are then bound to that effect key:
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.
To remove the keyboard grab, you can do any of the following:
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
via an external control such as OSC, joystick, or MIDI control
7.3 Effects, transitions and generators
Just as with rendered effects (or rather, filters) [section 4.12], we can divide our real time effects (filters) into three or more subtypes. The most common subtypes are effect (one frame input, one output), transition (two frames input, one output) and generator (no video inputs, one video output). There are also compositors (multiple frames input, one frame output). These are only used in the multitrack window, and will be discussed there [section 11.16]. With the RTE window open [section 7.1], you can see the type of each effect in the drop-down list, and it is also shown next to the key/mode area.
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-page-down keys will cycle the background clip. Realtime effects triggered from the keyboard are applied only to the foreground clip.
7.4 Applying to clips
In the Clip Editor, you can apply any real-time effects to a selection just as if it were a rendered effect [see also section 4.12]. Simply select the frames you would like to apply the effects to, and then click on Effects -> Apply Real Time Effects to Selection, or press the ctrl-e keys. When the effect is being applied, you can Preview what has been done so far by clicking on the Preview button. There is also a Pause button. If you click this you can again Preview what has been processed, or you can Resume processing. In addition you can choose to Keep what has been processed so far and not process any more. Otherwise, simply wait, and the effect should be applied to the selected frames. 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) !
7.5 Setting parameters, setting defaults, saving defaults
We saw in section 7.2, that one way to adjust parameters for a realtime effect is to grab the keyboard for that effect and then use the ctrl-up and ctrl-down keys to adjust the first numeric parameter, or the "t" key to enter textmode and change the first text parameter. Here we will look a little deeper into realtime effect parameters. One way to see the parameters of an effect is to open the RTE window (see section 7.1), activate the effect, and click on the Set Parameters button. This will open up a parameter window, and if the effect has parameters you will be able to set them here. Another way is to set defaults for the realtime effects. This is done by selecting the menu option VJ -> Set Real Time Effect Defaults, and selecting the effect, transition or generator from the menu list. Selecting an effect will open up a window, and if the effect has parameters you will be able to adjust them. If you want to keep the settings, click Set As Default, otherwise click Cancel. Note: For generators, you can also set the out channel size (i.e the pixel size of generated frames). Setting defaults only lasts for the current LiVES session, so if you want to make these defaults permanent, you need to select the menu option VJ -> Save Real Time Effect Defaults.
Tip: LiVES has only one set of parameter defaults, however you can switch between different sets of defaults by copying the file ~/.lives-dir/fxdefs to an alternate file and then restoring this at a later time.
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.
8.2 The k, m, t and tab keys
The following keys are explained more fully in section 7.2. "k" - grab keyboard for last activated effect key "m" - cycle effect mode for effect key with keyboard grab "t" - enter textmode for the effect that has key grab Tab - leave textmode
8.3 Bookmarking clips
If you have several clips open, you can mark the position of a clip with F1 through F11. For example, if you press F1, the current clip is connected with F1. If you then switch to another clip, and press F1, LiVES will return to the first clip. All of the keys F1 to F11 can be used to bookmark clips in this way. This works the same whether LiVES is playing or not. If you press the F12 key, all bookmarks will be cleared. Bookmarks only last for the current session of LiVES.
9 Recording
9.1 Recording, previewing and rendering
In the Clip Editor, it is possible to record any part of your performance. To initiate recording, press the "r" key. You can press the key before beginning playback, or at any time during playback. To end or cancel recording, press the "r" key again, or stop playback. You can toggle recording on and off multiple times during playback. If you press "r" before starting playback, you will see a message in the message area informing you that LiVES is ready to record. If you press "r" again without playing, you will get a second message informing you that recording was cancelled. In addition to pressing the "r" key, you can toggle record mode by clicking on the menu option Play -> Record Performance. The following types of events are always recorded:
frame changes
fps (frames per second) changes
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.
There are various options:
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).
Fig. 9.1.1 – choices after recording 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
10.1 Crash Protection
LiVES has full crash protection for clips, meaning that in the rare event of a crash, you can restart it and you should be able to recover all clips just as they were at the time of the crash. After a crash LiVES will ask on startup if you would like to attempt to recover the clips, click on OK to do so, or Cancel to ignore this. Note: Starting LiVES with lives -recover will force recovery of files in such a case, whilst starting it with lives -norecover will force a Cancel. [see also section 3.1].
10.2 Clearing disk space
LiVES has a facility in the Clip Editor to enable freeing up of any disk space which is no longer used. This tool should be run from time to time especially after a crash. To run this tool, click on the menu option File -> Clean Up Disk Space. After running, the tool will report how much disk space (if any) was recovered.
10.3 Setting the theme
You can alter the theme (skin or look) of LiVES, choosing from a variety of options. You can switch themes by going to Tools -> Preferences -> Themes. Here you can pick a new theme from the drop-down list, or choose to have no theme. After switching themes you will need to restart LiVES for the theme changes to take place. Currently, user defined themes are not supported - though this is planned as a future enhancement.
10.4 Resetting playback speeds and positions
When you switch to a new clip during playback in the Clip Editor, the new clip will continue from the last played frame and at the last frame rate for that clip. The menu option VJ -> Reset all playback speeds and positions will cause all clips to start playing from the first frame (frame 1), and at their normal playback rate.
10.5 MIDI/joystick learner
LiVES has the ability to link many of the VJ features to MIDI controllers and joysticks. This is activated through the menu option VJ -> MIDI/joystick interface -> MIDI/joystick learner
Once the window is opened you can press a joystick key or MIDI key, or MIDI controller.
On the left you will then see a cascade of controller/button/key - you can pick any one of these, then from the drop-down list, select a macro to link it to.
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 note off
MIDI controller
MIDI program change (as of version 1.1.0)
MIDI pitch bend (as of version 1.1.0)
the joystick/MIDI learner feature is very new, and the following should be noted:
joystick axis support may be flaky - there is currently no calibration
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 auto-detected. 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.
10.6 MIDI synch
LiVES can also optionally synch playback start and stop with a MIDI device. For this you need the scripts midistart and midistop installed. LiVES installs these files by default. Go to Tools -> Preferences - > Misc, and check the box labelled Midi synch. Now when LiVES starts playback it will send a MIDI pattern start to /dev/midi and when playback ends it will send a MIDI pattern end to /dev/midi.
10.7 Jack transport synch
LiVES can also synch playback with jack transport (see - http://jackaudio.org/) LiVES can synch as master and/or client. To activate jack transport synch, go to Tools -> Preferences -> Jack Integration, and select Jack Client and/or Jack Master. You can also choose whether you would like LiVES to start up the jack transport server when LiVES starts up. In Jack Master mode, starting playback in LiVES will cause all connected clients to start playback. In Jack Client mode, when another client starts jack transport, LiVES will begin playback.
Tip: jack transport synch is perfect if you want to use LiVES with another jack enabled program such as Ardour. In this case you could edit your audio in Ardour, and edit your video in LiVES, and have the playback of both synchronised through jack transport.
11 The multitrack editor
So far, we have been looking at the Clip Editor interface of LiVES, being the part of the application where individual clips can be edited, and where these clips can be freely played back. LiVES has a second, more structured interface, and this is the Multitrack Editor. In the Multitrack Editor, it is not possible to edit the individual clips, rather the clips can be brought together and rendered into a new clip. There are various ways to enter the Multitrack Editor:
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.
11.1 Setting multitrack details
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).
Fig 11.1.1 – multitrack details
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.
11.2 The multitrack screen layout
Once you enter multitrack mode, you will see the screen is split vertically into 3 areas. At the top is the "manipulation area", below this is the "timeline area", and at the bottom is the "message area". The manipulation area is split horizontally into three regions:
the preview window
the "polymorph" window
the context window
as shown here:
Fig. 11.2.1 - The manipulation area. The preview window shows playback and effect previews. 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 spin-buttons. 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).
Fig. 11.2.2 - the timeline area
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.
Fig. 11.2.3 - the message area 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.
You can return to Compact View by:
press the d key once
select the menu option View -> Compact view
or, click on the Compact View button.
11.3 Inserting video and audio
You can insert a clip by dragging one from the polymorph window onto a timeline track. If the polymorph window is not in clip mode, you can press 'c' to get there.
Tip: Alternately, you can use the keyboard. ctrl-page-up and ctrl-page-down will cycle through clips. ctrl-left and ctrl-right will move the timeline cursor. ctrl-up and ctrl-down can be used to change the current track. ctrl-i will insert the current clip at the current cursor position in the current track. You can also use the menu option Edit -> Insert selected clip (for video tracks), or Edit -> Insert selected clip audio, if the current track is the Backing Audio track. In standard insert mode, the insert point must be blank (i.e. free of other video). If the clip is too long, as many frames as possible will be inserted. In future there may be more types of insert mode. 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.
Fig. 11.3.1 - selecting a clip
Fig. 11.3.2 - dragging to the timeline
Fig. 11.3.3 - dropped on the timeline 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).
11.4 Playback in the multitrack editor
Playing back video and audio in the Multitrack Editor is very similar to playback in the Clip Editor. To start playback, either:
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
Fig 11.4.1 – play all button in Multitrack To stop playback, either:
press the 'q' key once, or
use the menu option Play -> Stop, or
click on the Stop icon in the toolbar
Fig 11.4.2 – stop button in Multitrack
In the Multitrack Editor, playback can also be paused. To pause playback:
press the 'p' key once during playback, or
use the menu option Play -> Pause, or
click on the Pause icon in the toolbar
Fig. 11.4.3 – pause button in Multitrack 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. To rewind the timeline position to 0, either:
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
Fig. 11.4.4 – rewind button in Multitrack
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
or click once on the Separate window icon in the toolbar
Fig. 11.4.5 – separate window button in Multitrack to deactivate separate window mode:
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. to activate full-screen mode:
press the 'f' key once
or select the menu option Play -> Full Screen
to deactivate full-screen mode:
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. to activate loop mode:
press the 'o' key once
or select the menu option Play -> Loop Continuously
or click once on the loop icon in the toolbar
Fig 11.4.6 – loop button in Multitrack toolbar
to deactivate loop mode:
press the 'o' key once
or deselect the menu option Play -> Loop Continuously
or click once on the loop icon in the toolbar
The audio can be muted as well: to mute the audio:
press the 'z' key once
or select the menu option Play -> Mute
or click once on the mute icon in the toolbar
Fig 11.4.7 – the mute button in Multitrack to un-mute the audio:
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.
Fig. 11.4.8 – volume slider in Multitrack
11.5 Adding tracks
You can add any number of video tracks you like to the Multitrack Editor. Tracks can be added either in front of the current stack, or at the rear of the current stack. Each video track may also have an associated audio track. It is not currently possible to add additional standalone backing audio tracks. To add a video track at the rear of the stack:
use the menu option Tracks -> Add Video Track at Rea
use the key combination ctrl-shift-t
To add a video track at the front of the stack:
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.
11.6 Selecting and trimming audio and video blocks
You can select a block by double clicking on it. If you do this, you will see the block gets marked with an "X" and the polymorph window will enter in/out mode.
Fig. 11.6.1 - double clicking on a block selects it
Fig. 11.6.2 - the polymorph window in in/out mode 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.
11.7 Splitting and deleting blocks
A block can be split into two parts, to enable each part to be manipulated independently. It is also possible to split blocks on several video tracks at the same point in time. To split a single block, either:
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). To delete a block, you can either:
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.
11.8 Mouse mode, snap mode and audio insert mode
The Multitrack Editor has various Mouse Modes. Currently there are just two modes,
Move and Select.
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.
Fig. 11.8.1 mouse mode, snap mode and insert mode 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.9 Moving blocks
Blocks can be moved around the timeline simply by clicking on them and dragging them to a new position. Mouse Mode must be in Move mode for this to succeed (see section 11.8). The Snap Mode affects the final positioning of the block (see section 11.8). Moving of blocks can be undone/redone from the Edit menu. If the block has effects associated with it, these may be moved with the block. To prevent this, you can deselect Effects -> Move effects with blocks.
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. To select and deselect video tracks:
you can select/deselect an individual video track by clicking in the small check-box at the very left of the timeline area.
Fig. 11.10.1 - three video tracks selected
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
To select a time period, either:
Left, right or middle click in the lower timeline area
Adjust the selection spin-buttons (start and end seconds)
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.
11.11 Inserting and removing gaps
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
menu option Tracks -> Insert gap in current track/selected time.
You can insert a gap in all selected tracks over the selected time by activating the
menu option Tracks -> Insert gap in selected tracks/time.
Blocks will be split as necessary and then moved to the right.
Effects are moved with blocks where possible, except if the menu option Effects ->
Move effects with blocks, is deselected.
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
first gap(s) in selected tracks/time, or use the key combination ctrl-f.
To remove all gaps in a region, use the menu option Tracks -> Close all gaps in
selected tracks/time, or use the key combination ctrl-g.
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).
Fig 11.11.1 – closing gaps Note: Gap insertion and removal can be undone and redone from the Edit menu.
11.12 Applying effects to blocks and regions
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. 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.
Fig. 11.12.1 - after applying an effect with parameters (colour correction) 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.3 - setting the parameter values
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.
Fig. 11.12.5 - Apply 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.
11.13 Audio effects
Audio effects can be applied to audio blocks, either blocks in the backing audio track, or audio attached to video tracks. There is one overall audio effect, this is the audio volume and pan effect. At the time of writing this is the only audio effect in LiVES, though in future there may be more. The audio volume and pan effect allows for fine tuning of the volume and pan of audio at each point in time. A coarser control is available through the audio mixer (see section 11.19), but this cannot be varied with time and cannot set the pan. When using the audio volume and pan effect, it can be extremely useful to visualise the parameters of the effect. This can be done via the menu option View -> Audio Parameters. Here you can select or deselect individual parameters to view. If you select a parameter to view, it will be shown as a horizontal line in the timeline. Adjusting the parameters of audio volume and pan is very similar to adjusting the parameters of a video effect. First we need to edit the effect, this is done in various ways, either:
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).
11.14 Video transitions
To apply a transition, first create a region with two tracks (see section 11.10). Then go to the menu option Effects -> Apply effect to region, and choose "transitions". In this example, we will use the "chroma blend" transition. This will give us a cross-fade between the two tracks. When you select "chroma blend", the polymorph window will go into effect mode. As above with an effect, slide the time slider all the way to the left. Then select "transition in". Transition in means that all of the front layer (in this case, layer 0) is visible.
Fig. 11.14.1 - setting the transition in at the start
Press Apply to store the parameter values. 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.
Fig. 11.14.2 - setting the transition at the end
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.
Fig 11.4.3 – crossfade audio
Note: the backing audio level is not affected by this. Applying transitions can be undone/redone from the Edit menu.
11.15 Audio only transitions
Audio only transitions may be used to bring audio from a layer behind the front layer so that it is audible. If you want to cross-fade the video as well, use an Audio/Video transition (see section 11.14). To use an audio only transition, first select two tracks and the time period you want to apply the transition over. Then activate the menu option Effects -> Apply effect to region -> Transitions -> Audio only Transitions and select a transition you want to use (at the time of writing there is only one option). Now as with any other effect/transition, you can set the time slider to a time position for example the start, set the parameter(s) as you wish, then click Apply. Now you can set the time slider to another value (for example, the end) , set the parameters, and click Apply again. Applying an audio only transition can be undone/redone via the Edit menu. Remember also that the volume (and pan) of each layer is also affected by any audio effects applied (section 11.13), and by the mixer level for that layer (section 11.19). Audio transitions are only available when audio track per video track is enabled (see section 11.1).
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.
Fig. 11.16.1 - LiVES with 3 video tracks
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.
Fig. 11.16.2 - three video tracks selected
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.
Fig. 11.16.3 - three tracks selected and a time period
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 ctrl-up and ctrl-down.
To learn how to set the timeline position, see section 11.4.
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.
Fig. 11.16.4 - compositor parameters when no frame is present
Fig. 11.16.5 - compositor parameters when a frame is present
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 Click on Apply when you want to set some values. 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. Applying a compositor can be undone/redone from the Edit menu.
11.17 Listing, deleting, editing effects
Listing, deleting and editing of effects at a particular point is done in the following way. First, you can list the effects at a particular point (current track/timeline position) by either:
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.
Fig. 11.17.1 – the effects list
To delete an effect, either:
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. To view or edit an effect, either:
double click on the effect name in the polymorph window
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.
11.18 Filter maps
In LiVES terminology, a Filter Map is a point on the timeline where the order in which effects are applied is defined. Thus if you want to change this order, you need to make the change in a filter map. Note that any time an effect is switched on or off in the timeline, LiVES adds or updates a filter map at that point. If you want to change the order of effects, first you need to list the effects at a point where you want to change the order (see section 11.17). Then click on the button marked Prev filter map. This will take you to the filter map prior to or at the selected point. You may wish to go back further by pressing Prev filter map again. If you go too far back, you can press the button marked Next filter map to go forwards in time to the next filter map. Once you have found the correct filter map position (basically, the start point where you want to change the order from) then in the effect list in the polymorph window, you can click on the name of effect which you wish to move, in order to select it. Next, click on either the Insert before or Insert after button, and then on a second effect. The first selected effect will be moved before or after the second selected effect.
Fig 11.18.1 – selecting an effect at the filter map
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.
11.19 Audio channel controls
The Multitrack Editor has a simple audio level mixer. You can enter the audio mixer by clicking on the Audio mixer button, or by pressing crl-m.
Fig 11.19.1 – the Multitrack audio mixer
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.
11.20 Marking the timeline
During playback in Multitrack mode, you can mark the timeline by pressing the 'm' key. This will leave a small line on the timeline. This can be useful if you want to note the position in time of certain events, for example dramatic changes in the background music, changes in dialogue and so on. Afterwards you can position the timeline pointer near the mark.
Fig. 11.20.1 – making your mark on the Multitrack timeline
To clear all marks from the timeline, use the menu option Edit -> Clear marks from timeline.
11.21 Saving, loading and deleting layouts
If you have created a layout in the timeline which you would like to keep, to continue working on later, you can do so by activating the menu option File -> Save layout as. It is recommended that you save your layouts in the defined directory - that way LiVES will know to maintain it as part of the clip Set. When saving a layout, you can choose whether or not to enforce the same width, height and audio values when the layout is loaded (this also depends on the load settings, see below). If you want this, then select the menu option Edit -> Retain width, height and audio values in saved layouts. Note that the frame-rate for a layout is always fixed regardless of any settings. 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).
11.23 Leaving multitrack mode
There are various ways to exit Multitrack mode and enter the Clip Editor:
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
By double clicking on a thumbnail in the polymorph window to edit that clip
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.
11.24 Layout 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.
Fig. 11.24.1 – Layout warning example
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.
Fig. 11.24.2 – layout errors window (example)
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)
Warn if a clip used in a layout is about to be closed.
Warn if frames used in a layout are about to be deleted
Warn if audio used in a layout is about to be deleted
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:
Warn if frames used in a layout are about to be shifted
Warn if frames used in a layout are about to altered
Warn if audio used in a layout is about to be shifted
Warn if audio used in a layout is about to be altered
11.25 Return to Sets and project save/load (layouts)
Layouts are consider part of a Clip Set, that is, if a Clip Set is renamed, merged or deleted the layouts are moved, merged or deleted with the rest of the Clip Set (see section 4.7). Layouts are also considered part of a Project, and are saved and loaded inside LiVES project files. See section 4.8.
11.26 View event list
Every layout in LiVES is stored internally as an Event List. You can view the Event List by activating the menu option View -> Event list. Since there may be many thousands of frame events, it is possible to filter these out by deselecting the option View -> Show FRAME events. An Event List is also created during recording, and it is possible to view this event list also (see section 9). 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).
12 Advanced features - streaming
12.1 LiVES to LiVES streaming
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.
Fig. 12.1.1 – LiVES TO LiVES stream send
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 full-screen/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.
Fig. 12.1.2 – LiVES to LiVES stream receive
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.
12.2 yuv4mpeg streaming
LiVES can also send and receive streams in yuv4mpeg format. Currently only video streams are supported, but in the future, audio streaming will be also possible. Enabling yuv4mpeg streaming support in LiVES is quite simple. If you have mjepgtools 1.6.2 or higher installed at compile time, LiVES will auto-detect this and add yuv4mpeg (streaming) support. Most LiVES packages now have yuv4mpeg support built in. If not, make sure you have mjepgtools installed and recompile LiVES from source. 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.
Other examples: lives-exe | yuvscaler -M WIDE2STD | yuvplay
lives-exe | mpeg2enc -o output.avi
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
13 Advanced features - remote control/monitoring
13.1 OSC control
LiVES implements a standard version of Open Sound Control (http://www.opensoundcontrol.org). LiVES currently supports libOSC and sendOSC from here: http://www.cnmat.berkeley.edu/OpenSoundControl/index.html LiVES is now compiled with OSC support by default. There are several ways to activate it: start up LiVES with, e.g.: lives -oscstart 9999
this will start up LiVES with OSC enabled on UDP port 9999. Or, start up LiVES normally and go to Tools -> Preferences -> Streaming. Here you can tell LiVES to open a UDP port (default 9999, this can be changed). You can also ask LiVES to open an OSC port every time it starts up (doing this can be a security risk, please check your firewall settings first !) You can then send commands using sendOSC. The autolives.pl script shows a sample implementation of it. If using the default port (9999) you can just type: autolives.pl, for other ports, use autolives.pl localhost <port> where <port> is the UDP port number in Preferences. You can also run autolives.pl from another host using autolives.pl <host> <port> Note: for LiVES version 1.1.0 and higher, maximum OSC latency is just 4 ms. For older versions there is a maximum latency of up to 40 ms for OSC commands to be processed in LiVES. However this is not guaranteed - depending on what the application is doing, commands could be processed slower. For example, loading a large frame from disc could block for several (even tens of) milliseconds. See section 17.3.4 for a complete list of OSC commands.
13.2 Status socket
LiVES can open a status socket back to the controller. This is used to return information from LiVES to the controller. See section 17.3.4 for a complete list of OSC commands.
13.3 Notify socket
LiVES can open a notify socket back to the client. LiVES will send messages over the notify socket when certain events happen in LiVES, for example when a new clip is imported, or when a video frame (synch) is shown. An example of this is in the Perl script tools/monitorlives.pl which is shipped with LiVES. See section 17.3.4 for a complete list of OSC commands.
Section 17.3.5 shows a list of notified events.
14 Advanced features - batch processing
LiVES has an external tool for batch mode processing of clips. Right now this is of fairly limited use, but can easily be expanded to make it more powerful.
The script is in the tools directory shipped with LiVES, and is named batchproc.pl.
The script will process each clip in turn and takes a single OSC command as its argument. An example command might be:
/clip/encode_as,<filename>,[<width>,<height>]
(width and height are optional.)
[see section 17.3.4 for a complete list of OSC commands].
The OSC command will be applied to each clip in turn.
There is a parameter which takes the current clip (index) number, and this is $clip. Here is an example to make things clearer:
tools/batchproc.pl "/clip/encode_as,/home/user/file$clip.mpg"
This would cause each loaded clip in turn to be encoded using the currently selected encoder/codec using its current frame size. The name of the first clip would be /home/user/file1.mpg, the second /home/user/file2.mpg, etc.
You can also force the size of the encoded clip, for example: tools/batchproc.pl
"/clip/encode_as,/home/user/file$clip.mpg,640,480"
would force a resize of each clip to 640 x 480 before encoding.
Note: depending on the codec used, it may not be possible to encode at exactly the size requested, in which case the nearest valid size will be used.
15 Advanced features - RFX builder tool
RFX is one of the standards developed for LiVES. Originally, it stood for Rendered Effects (FX) standard. It consisted of a script for generating a plugin, and a set of parameters and layout hints for input of the parameters for the script. This has now split into two parts - the RFX scripting part is used for rendered effects, but the RFX parameters and layout part proved its usefulness and is now used for other types of plugins; for example, the realtime plugins and the encoder plugins now use RFX parameters and layout. 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 sub-options
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
There are three status levels for RFX scripts in LiVES:
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.
The fields in the RFXbuilder window
Type
The first field in the LiVES rfxbuilder window is “type”
RFX scripts in LiVES are divided into types, those types are currently:
effects
tools
transitions
generators
utilities
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)
The remaining fields vary depending on the parameter type.
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.
Parameter Window Hints
This section is used to give the interface (in this case LiVES), some hints about how to lay out the parameter window.
There are two types of hints currently available in LiVES RFX builder.
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:
aspect framedraw
transalign
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.
Fig. 15.1 – the RFX builder tool
Saving and rebuilding
Once the script is ready, you can save it. After saving, you can activate the menu
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 full-screen/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 last-resort 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 frame-rate. 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).
Open Sound Control – Open Media Control
The following settings are for Open Sound Control using the Open Media Control command set. OMC remote control enabled – check this button if you wish to enable Open Media Control remote control for the remainder of the session. Once activated, this cannot be deactivated without restarting LiVES. UDP port – here you can enter the UDP port which LiVES will listen on and clients can connect to. The value can only be changed when OMC control is inactive. Start OMC on startup – if this option is selected, LiVES will start up the OSC/OMC listener on the selected port each time it starts up.
See section 13 for more details about OSC.
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.
17.3 Technical documentation
17.3.1 Weed specifications
Weed effect specification - used for realtime filters
Weed spec.
Weed audio extension
Weed audio spec.
Weed events specification
Weed events spec.
17.3.2.1 LiVES-perl reference
LiVES-perl spec.
17.3.3 Plugin formats
17.3.3.1 Encoder plugins
Encoder plugins in LiVES take a sequence of jpeg (and optionally png) files, and optionally a raw or wav audio file, and produce a file output. Encoder plugins can be written in any language. They can also produce several different formats if required and they can prompt the user for extra parameters (e.g. a quality setting). Most encoder plugins are written in Perl (this has some advantages, the variables are parsed and named for you), although this is not necessary. However, for this example we will use Perl for the code and take a snapshot CVS version of the mjpegtools_encoder. For other languages, the code will be similar, however you will need to parse the variables yourself. Here is the example encoder we will look at; note that the current version may be slightly different from this. http://lives.cvs.sourceforge.net/lives/lives-plugins/plugins/encoders/mjpegtools_encoder?revision=1.7&view=markup LiVES encoder plugins use a system of "directives". That is, the plugin is called (sometimes via an intermediary program) with a string of parameters. The first parameter is the "directive", and the program should act and produce different output depending on this directive. Lets take a look at the example encoder_plugin. After some starting comments, we have: (Note: lines are numbered below solely for convenience.) 33
###############################################################
########
34
35 if (!defined($standalone)) {
36 my $smogrify=`which smogrify`;
37 chomp($smogrify);
38 require $smogrify;
39 }
40 else {
41 $command=$ARGV[0];
42 }
43
44
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. 44
45
###############################################################
########
46 $tmpvid="tmpvid.m1v";
47 $tmpaud="tmpaud.mpa";
48
Here we just set some variables for temporary files. 49 if ($command eq "version") {
50 print "mjpegtools encoder plugin v0.96\n";
51 exit 0;
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. Finally, to indicate that encoding is complete, you *MUST* create a file
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". 367 if ($command eq "clear") {
368 # this is called after "encode"
369 # note that encoding could have been stopped at any time
370 if (-f $tmpvid) {
371 unlink $tmpvid;
372 }
373 if (-f $tmpaud) {
374 unlink $tmpaud;
375 }
Write "completed" to .status: 376 &sig_complete;
377 exit 0;
378 }
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
384 # ...
385
386 # end finalising code
387 print "finalised\n";
388 exit 0;
389 }
390
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.
17.3.3.2 Real-time effect plugins
Realtime effects may optionally include the header files weed-utils.h and weed-plugin-utils.h
Including these files provides the following very useful functions:
Weed utils library
Weed plugin-utils library
See also the Weed spec., section 17.3.1.
Here is an example of a realtime effect, which uses the Weed effect standard (section 17.3.1). Comments are in bold.
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; for (;src<end;src+=irowstride) { for (i=0;i<width;i++) { dst[i]=src[i]^0xFF;
} dst+=orowstride;
} return WEED_NO_ERROR; }
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_PALETTE_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; }
17.3.3.3 Video playback plugins
Video playback plugins must implement some mandatory functions and there are also some optional functions. The plugins may be written in C or C++.
You should include the header file “videoplugin.h” found in the LiVES source distribution. You may wish to include “weed.h” and “weed-effect.h” to use palette names.
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.
const char *version (void) Should return a version string.
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.
Optional functions
const char *get_description(void) Should return a description string.
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.
This is the SDL playback plugin.
// LiVES - SDL playback engine
// (c) G. Finch 2003 - 2008 <[email protected]> // 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 "videoplugin.h" #include <stdlib.h>
//////////////////////////////////////////////////////////////////////////////////// static char plugin_version[64]="LiVES SDL playback engine version 1.2"; static char error[256]; static int (*render_fn)(int hsize, int vsize, void **pixel_data, void **return_data); static boolean render_frame_rgb (int hsize, int vsize, void **pixel_data, void **return_data); static boolean render_frame_yuv (int hsize, int vsize, void **pixel_data, void **return_data); static boolean render_frame_unknown (int hsize, int vsize, void **pixel_data, void **return_data); static int palette_list[6]; static int mypalette; static int clampings[2];
///////////////////////////////////////////// // SDL specific stuff #include <SDL.h>
static SDL_Surface *screen; static SDL_Surface *RGBimage; static SDL_Overlay *overlay; static int ov_hsize; static int ov_vsize;
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||palette==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_mask|MOD_NEEDS_TRANSLATION));
}
} }
return TRUE; }
17.3.3.4 Decoder plugins
Decoder plugins in LiVES use a very simple interface, although internally they may be fairly complex. All decoder plugins must implement a few mandatory functions, and there are also a few optional functions. Decoder plugins may be written in C or C++. It is recommended that decoder plugins include the header file decplugin.h from the LiVES source distribution, as this contains some common definitions. They may also wish to include weed.h and weed-effects.h for palette definitions.
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 char *version(void) Return a version string.
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 weed-effects.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.
17.3.4 List of OSC commands
LiVES OMC commands
http://lives.svn.sf.net/viewvc/lives/trunk/OMC/lives-OMC.txt
17.3.5 List of OSC notify events
#define LIVES_OSC_NOTIFY_FRAME_SYNCH 1 // sent when a frame is displayed #define LIVES_OSC_NOTIFY_PLAYBACK_STARTED 2 // sent when a/v playback starts or clip is
switched
#define LIVES_OSC_NOTIFY_PLAYBACK_STOPPED 3 // sent when a/v playback ends
#define LIVES_OSC_NOTIFY_QUIT 64 // sent when app quits
#define LIVES_OSC_NOTIFY_CLIP_OPENED 128 // TODO - msg_string starts with new clip number #define LIVES_OSC_NOTIFY_CLIP_CLOSED 129
#define LIVES_OSC_NOTIFY_CLIPSET_OPENED 256 //msg_string starts with setname #define LIVES_OSC_NOTIFY_CLIPSET_SAVED 257
#define LIVES_OSC_NOTIFY_SUCCESS 512
#define LIVES_OSC_NOTIFY_FAILED 1024
#define LIVES_OSC_NOTIFY_CANCELLED 2048
17.3.6 LiVES clip format
Clip format
17.3.7 LiVES backup format
The backup format is simply a tarred and gzipped version of the clip format (section 17.3.6). For historical reasons, there may be tar files within the main tar file. These should be extracted also. The file extension of these files is normally set to .lv1.
17.3.8 LiVES Set and project format
Set format:
<tmpdir>/<setname>/clips/nnnnnnnnn/ - various clip directories, format as in section 17.3.6. nnnnnnnn is a randomly assigned unique (for the set) number. <tmpdir>/<setname>/order – order file, contains entries of <setname>/clips/nnnnnnnnnn separated by newlines. <tmpdir>/<setname>/layouts – layouts directory, with binary dumps of event lists (see section 17.3.1). <tmpdir>/<setname>/layouts/layout.map - layout map file.
Layout map file format:
4 bytes handle len
n bytes handle
8 bytes unique_id 4 bytes clip file name len
n bytes clip file name
4 bytes data len n bytes data
where data is a text dump of:
layout_file_file_name|clip_number|max_frame_used|clip_fps|max_audio_time|audio_rate
<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.
17.4 Remote scripting examples
autolives.pl
monitorlives.pl
18 Toys
18.1 Mad frames
When Mad Frames is activated, random frames from the current clip are shown in the start and end windows during playback.
