Theora Cookbook

Ogg Theora is the best free software video codec for streaming video available. It has been around for a few years now and was developed by the same people that brought you the popular audio codec Ogg Vorbis.

Ogg Theora as yet doesn't have too many tools available for editing or streaming, but with a bit of persistence and some nifty command line tools you can do a lot with it.

Icecast2 supports Ogg Theora and the Cortado applet allows you to embed live or archived Theora video easily in a webpage. There is really alot you can do with it and it matches any modern streaming video codec for streaming. Ogg Theora is an excellent choice for most of your online streaming video needs.
 

Using VLC to play Streams

Software name : VLC
Software version  : 0.8.4

VLC will play just about every format there is. Notably it is about the only player across platforms that plays back Ogg Theora video streams. To play video streams follow these quick steps:

When you have VLC installed launch the application. You should have something that looks like this (on all platforms):

What we want to do is choose the Open Network Stream from the file menu:

Now you should see a window that looks something like this:

Now,...I am going to assume you are looking to open a Ogg Theora live stream with an address like:

http://24.72.34.35:8000/theora.ogg

If this is the case, then you need to enter this information (the stream location) into the interface. You enter this content by first choosing the HTTP/HTTPS/FTP/MMS item :

Then you must enter the stream location into this field:

You should then press ok and hopefully you see and hear your stream!

Streaming Video with FFMPEG2Theora

This method focuses on streaming video from a DV or Firewire camera using Linux. The video stream will be Ogg Theora which means your users will be able to watch using Theora enabled player or in a java applet such as Cortado.

There are two ways of doing this. The hard way and the easy way. The hard way is to do everything by hand (installing everything from source). In fact when I wrote this document originally, that was the only way to do it. However things have progressed and now there is an easier way. The easy way is to use Debian (or maybe Ubuntu, I haven't tested this) and use the Debian Packages.

In case you can't use Debian or you want to make your life hard for no good reason, then I have included this process as well. To go this route it will help to be familiar with Linux. In fact, don't go much further unless down the hard road unless you know how to find your way around Linux and you should also know a little about modules, compiling software from the command line, and using a command line interface for executing software. Following this process as a 'newbie' could be tricky. I provide as much information about the process as I can but there are a lot of issues that you may need to resolve that I cannot account for here. Certainly as a 'moderately' experienced Linux user you should be ok. 

Getting Ready

• A Firewire camera is not the same as a DV camera. However for the intents of this manual they work the same.
• Firewire is known also as ieee1394

Requirements

You will need the following:

• DV cam
• Linux machine with firewire inputs
• firewire cable
• internet connection
• access to a 'theora-enabled' Icecast2 server (you need the IP address of the server, the port you should use, and the password)

In addition to the above you need to have raw1394 support for your firewire devices. raw1394 is a kernel module. A kernel module is a small extension to the operating system that enables specific functionality that is not included in the kernel itself. Kernel modules work similar to plugins in other applications, except they extend the functionality of the entire operating system not just a single application.

You may not have raw1394 support. To check if you do open a terminal and type the following:

lsmod

You may see a long list of items similar (but not exactly the same) to this:

Module                  Size  Used by
md5                     7680  1
ipv6                  234784  12
lp                     13448  0
via_agp                11264  0
sworks_agp             10912  0
sis_agp                 9988  0
nvidia_agp              9756  0
intel_mch_agp          11792  0
efficeon_agp           10144  0
ati_agp                10380  0
amd64_agp              13640  0
amd_k7_agp              9740  0
ali_agp                 9216  0
autofs4                18820  1
af_packet              20104  0
i810_audio             36884  1
soundcore              11104  2 i810_audio
ac97_codec             20108  1 i810_audio

Look in this list for raw1394. If you see it then great! If not then type this:

modprobe raw1394

Then retype lsmod and you may see something like this:

Module                  Size  Used by
raw1394                28396  0
md5                     7680  1
ipv6                  234784  12
lp                     13448  0
via_agp                11264  0
sworks_agp             10912  0
sis_agp                 9988  0
nvidia_agp              9756  0
intel_mch_agp          11792  0
efficeon_agp           10144  0
ati_agp                10380  0
amd64_agp              13640  0
amd_k7_agp              9740  0
ali_agp                 9216  0
autofs4                18820  1
af_packet              20104  0
i810_audio             36884  1
soundcore              11104  2 i810_audio
ac97_codec             20108  1 i810_audio

The first line says raw1394 28396 0 which is good news. If you see something similar to this then this is also good! You can also try checking dmesg (just type dmesg on the command line and look for something signifying the raw1394 module is ok - if you see nothing mentioned then chances are raw1394 is not installed). Otherwise you are going to have to take the long road home and get raw1394 support in your kernel modules. This can be complicated as it depends on what version your kernel is etc etc. A good starting point for this research would be here:

http://www.linux1394.org/

Set-Up

Assuming you have the raw1394 module running, lets start setting up the software you need. We will need to install the following applications:

• dvgrap
• ffmpeg2theora
• oggfwd.

The Easy Road 

With Debian 4 you can run this command line (using stable sources):

apt-get install libshout3 libshout3-dev dvgrab ffmpeg libtheora0 libtheora-dev oggfwd 
ffmpeg2theora 

The above command should all appear on one line. Now, with luck you have everything you need to get started. So first we need to plug in the dv (or (firewire) camera to the computer. You need to attach the firewire camera to the firewire socket on the camera, and the other end of course goes into the firewire socket of your laptop or whatever computer you are using.

Now, turn on the camera. Check the raw1393 module is loaded by using lsmod (see the section near the beginning of this document on raw1394).

ok, so the thing is you will need know is to execute the following line on one command line. You will need to use the streaming server details you have for the Icecast2 (theora-enabled) server. The command is:

dvgrab --format raw - | ffmpeg2theora -a 0 -v 5 -f dv -x 320 -y 240 -o /dev/stdout - | 

oggfwd  icecastserver  8000 pwd /theora.ogg

Remember the command will have to be all on one line (the above example is not). Also replace the details:

• icecastserver
• 8000
• pwd

with the details you have from your Icecast server. icecastserver should be replaced with the hostname or IP address of the streaming server. 8000 is the port number and is probably the same. pwd should be replaced by the password of your server. Lastly, you can replace /theora.ogg with anything as long as it starts with a forward slash (/) and ends in .ogg.

Now, you should be streaming! To check the connection use VLC .

The Hard Road 

dvgrab

You can find the source code and installation packages for dvgrab here - http://www.kinodv.org/

There are a number of ways to install software on Linux. The method very much depends on the tpe of Linux you are running. I am going to go through the following methods as they are the most popular:

Installing dvgrab on Debian

Installing dvgrab on Debian based systems should be quite easy. Debian has a package management application called apt. The process for installing software in debian usually follows this process using apt (you usually have to be online for this) :

step 1 - Type the following into the command line (terminal):

apt-cache search dvgrab

You will hopefully see something like this in the terminal window:

dvgrab - grab digital video data via IEEE1394 links

The command apt-cache search dvgrab looks for applications online in the Debian repositories (places where software is stored) and if it finds one with a name matching dvgrab then it lists those applications. To get familiar with how this works try the same command (apt-cache search) with different application names eg. apt-cache search mozilla

So, the output in the terminal window will either return nothing (a blank line) or some output such as that illustrated above. The above output gives the name of the application that matches your search (in this case dvgrab) and a short description ("grab digital video data via IEEE1394 links").

Now, if you see this then this is good news. The application is available from the repositories and we can install it. If the returned output was a blank line it means the repositories listed don't contain the software you are after, in which case you can do one of two things:

• install by source (see details below)
• learn about apt and alter the sources.list to include a repositry with your software. This can be tricky but its good to know. To start your research read this:

http://www.debian.org/doc/manuals/apt-howto/index.en.html

step 2 - So, assuming the repositry has dvgrab you need to install the software. Under Debian this is very easy, however you may have to (depending on how your operating system is set up) use the sudo or su commands for step2. This is because your user account may not allow you to install software but it will have to be done by root. I will explain this more below, in the meantime lets first look at the basic commands:

apt-get install dvgrab

This should download the required packages and install. The process may ask for some feedback (it may ask you to verify its the right package etc) in which case you should read the messages in the terminal window carefully before deciding. If all is well, you will then have installed dvgrab.

To test if dvgrab is installed type this in the terminal:

dvgrab --version

You will hopefully get an output similar to this:

dvgrab 1.8

This means you have dvgrab version 1.8 installed (your output might contain a different version number).

If you can't get the software installed via apt-get it might be because your user account does not have permission to install software. In which case you will need to use the su or sudo commands. These allow you to install software as the root user. su will log you in as the root user and then you can execute any commands you like under root. Be careful if you choose this way as you can accidently do a lot of damage to your operating system if you carelessly type the wrong command as root. To use su just type the command in the terminal and hit return. Then you will be prompted for the root password. if you do not know the root password for your system then you cannot use this method unless the system administrator sets it up for you. Once you have entered the root password you can follow the install steps above and all should be ok.

The other process to consider using is with sudo. sudo is short for super-user-do. So any command entered after sudo will be executed as root (superuser). So, type this:

sudo apt-get install dvgrab

You will then be prompted for a password. Enter your user account password not the root password. Then, if all is well, apt will install dvgrab. If all is not well and you get a permission error then you need to contact the system administrator and ask them if they will give you permission to use sudo (they do this by altering the sudoers file which is found at /etc/sudoers , for more info on this see http://www.courtesan.com/sudo/man/sudoers.html )

Installing dvgrab on Gentoo

Gentoo is another variety of Linux and it has its own package manager called emerge. The emerge system is pretty easy to use also and it usually contains more up-to-date versions of the software that Debian. To check if a package is available in emerge you should go to the Gentoo Online Package Management Database ( http://packages.gentoo.org/ ) and on the left you will see a search form. Enter dvgrab in the form field and click the "search" button (or press return).

Hopefully, you will get a page explaining to you some details of the dvgrab package for emerge. Now, to install type:

emerge dvgrab

You may have to use su or sudo to do this (see notes above in FFmpeg2Theora.Installing under Debian). Now test by typing :

dvgrab --version

Installing dvgrab on Redhat

I'm not so experienced on Redhat so if there are any Redhat gurus reading this I would appreciate any help in providing better information for using rpm to install dvgrab.

To install you need to use the Redhat Package Manager which is also known as rpm. To find package for Redhat you need to go online with a browser and look for a package database. rpmfind is a good one:

http://rpmfind.net/

There is a search form on this page that you should enter dvgrab and press return. You will be presented with a list of files that relate to your search term.Scroll down the page and find the package that suits the hardware of your machine. If you have a Pentium processor choose a version with 386 in its name. If you dont know the type of hardware you have then try 386 or try installing from source (see below). The example file I will use is dvgrab-1.7-3.i386.rpm

Now download the file. To install the downloaded file, type the following (make sure your terminal is in the same directory as the downloaded file):

rpm -i dvgrab-1.7-3.i386.rpm

Now the install process should just run its course. To test the install try this in the terminal:

dvgrab --verbatim

and refer to the notes on testing in the above sections.

Installing dvgrab from source

This is always the fallback method for installing if all else goes horribly wrong.

To install from source first you need to download the latest sources. Open this page in your browser: http://www.kinodv.org/

Then goto the dvgrab download section and download the latest sources. In this case the latest source file is dvgrab-1.8.tar.gz.

Now, in a terminal (ensuring you are in the same directory as the downloaded sources) type the following:

tar zxvf dvgrab-1.8.tar.gz

Remember to replace dvgrab-1.8.tar.gz with the name of your downloaded file.

This command decompresses the archive file and creates a new directory with the source files in it. You will now have to change directories and go into the newly created directory. In a terminal type:

cd dvgrab-1.8

Remember your new directory might be called something other than dvgrab-1.8 , to check type ls in the terminal and you will see a list of files and directories. From this you can see the right name of the new directory.

Now type:

./configure

If all is good, you can then type:

make ; make install;

and the software will be installed. However probably you have this error:

configure: error: avc1394.h not found, install libavc1394-devel

If you get this it means one of the dependencies hasn't been met. So you have to install this libavc1394-devel. Usually what I do in this situation is google for the lost package. If we do this, the first link is to this page: http://sourceforge.net/projects/libavc1394/

This is the homepage for the libavc1394 software. At the time of writing the latest version is libavc1394-0.5.1 . Download this file and decompress the file like so (make sure your terminal is in the right directory):

tar zxvf libavc1394-0.5.1.tar gz

The change directories to the newly created source directory:

cd libavc1394-0.5.1 

then do the configure:

./configure

then type the make and make install as so:

make ; make install;

You may need to use su or sudo to do this (see above sections). Now change back to the dvgrab source directory and do a configure again:

./configure

Then all should be good (no error messages) and so do the following:

make ; make install;

(you may need to use su or sudo for this too. Thats it! Now test with:

dvgrab --version

notes

• if you would like to know more about dvgrab visit the developers website:

http://www.kinodv.org/

• if you wish to read the manual that was installed with dvgrab the use the man command like so:

man dvgrab

oggfwd

There are two ways of installing oggfwd, from source of by downloading a pre-compiled binary. The first way is similar to the process we went through with dvgrab, the second (installing the binary) means that you simply download the application and run it without any need to install. If you are a Debian user you can use :

apt-get install oggfwd 

First however you need to install a libshout-2.1 which is a library of code that oggfwd uses. To install libshout-2.1 first download it from here (Debian users could first try apt-get install libshout3-dev):
http://v2v.cc/~j/ffmpeg2theora/oggfwd/libshout-2.1+svn.tar.gz

Download this and decompress using the following:

tar zxvf libshout-2.1+svn.tar.gz

Now change directories to the newly created directory:

cd libshout-2.1

and run the configure script:

./configure

If all is well do a make and make install (it may need to be done using su or sudo, check the notes above for dvgrab).

make ; make install;  

Installing Oggfwd from source

First download the file oggfwd.tar.gz and then decompress it using the terminal command:

tar zxvf oggfwd.tar.gz

Then change directories to the newly created directory

cd oggfwd

Now compile the binary

make

Now install the compiled binary

make install

This last step may need to be done using su or sudo (see the dvgrab section above).

To test if it is installed type

oggfwd

and you should see an output in the terminal like:

usage: oggfwd hostname port# password target
sample: oggfwd icf.de 8100 abc123 /cast.ogg 

Using the Oggfwd pre-compiled binary

To use the pre-compiled binary simply download the file oggfwd.linux.bin and execute it like so:

./oggfwd.linux.bin

and you should see something like this:

usage: oggfwd hostname port# password target
sample: oggfwd icf.de 8100 abc123 /cast.ogg

Now, to use oggfwd.linux.bin you need to change its permissions, copy it to the directory that contains all your other binaries, and change its name to oggfwd.

Change the permissions and move it to /usr/bin (renaomg it to oggfwd at the same time):

mv oggfwd.linux.bin /usr/bin/oggfwd
chmod 755 /usr/bin/oggfwd

Now, if you simply type oggfwd the application should start and give the same output in the terminal as described above.

ffmpeg2theora

ffmpeg

You must install the latest version of ffmpeg from the development site http://ffmpeg.sourceforge.net/index.php

If you know how to use CVS then you can check out the CVS files and use them to build ffmpeg . If you don't know how to use CVS then I have downloaded the files for you from CVS and you can find them here: http://www.xs4all.nl/~adam/source/ffmpeg_101205.tar.gz

When the file is downloaded, decompress the file with the following command:

tar zxvf ffmpeg-0.4.9-pre1.tar.gz

Remember to replace ffmpeg-0.4.9-pre1.tar.gz with the actual name of your file.

Next, change directories to the source directory:

cd ffmpeg-0.4.9-pre1.tar.gz

You directory may be named slightly differently from the above example. Now, we need to do a configure but with a parameter included in the command, this is to enable ogg vorbis support.

./configure --enable-vorbis

Now do a make and make install (may need to be done using su or sudo, see the notes above for isntalling dvgrab).

make ; make install;

It might take a long time to compile and install.

To test it all went well type this:

ffmpeg -v

You should see an output in the terminal similar to this:

ffmpeg version 0.4.9-pre1, build 4718, Copyright (c) 2000-2004 Fabrice Bellard
  built on Sep  6 2005 23:39:39, gcc: 3.3.6 (Debian 1:3.3.6-7)

libtheora

Theora is the codec you need to stream, in other words its the format of the streamed video. To use theora you need to install the libraries that enable it. I think it is best to install the latest one from source, so we will only look at this method. You may wish to try other ways for Debian, Gentoo etc. It is also worth noting that you could try installing libtheora-mmx instead off libtheora as it is faster. According to the oggfwd and ffmpeg2theorammx version is 2-3 times quicker. If you want to try this you can follow the below steps, but instead of using the sources from http://www.theora.org you could try : http://downloads.xiph.org/releases/theora/libtheora-mmx-1.0alpha5.tar.bz2

If you wish to try the 'plain vanilla' sources get them from : http://www.theora.org/

At the time of writing the latest source file is libtheora-1.0alpha5.tar.gz, so we will download this and decompress like so:

tar zxvf  libtheora-1.0alpha5.tar.gz 

Now change directory to the new source directory:

cd libtheora-1.0alpha5

Try running the configure script:

./configure

Now do a make and make install. It might need su or sudo (see above in dvgrab section).

make ; make install;

Hopefully all is well, and we can continue with installing ffmpeg2theora.
 

ffmpeg2theora

Download the package from here (we will only install from source): http://www.v2v.cc/~j/ffmpeg2theora/download.html

The file I am working with is ffmpeg2theora-0.15.tar.bz2, to decpmpress this try this command:

tar xvfj ffmpeg2theora-0.15.tar.bz2

Now change directories to the new source directory:

cd ffmpeg2theora-0.15

Now try the configure process

./configure

Then a make and make install:

make ; make install;

phew.....hopefully your are now done, to test ffmpeg2theora try this:

ffmpeg2theora

and you should see a lot of information appear on how to use the application, the output should be similar to this:

ffmpeg2theora 0.13

usage: ffmpeg2theora [options] input

Output options:
--output,-o alternative output
--width, -x scale to given size
--height,-y scale to given size
--aspect define frame aspect ratio: i.e. 4:3 or 16:9
--crop[top|bottom|left|right] crop input before resizing
--videoquality,-v [0 to 10] encoding quality for video
--videobitrate,-V [45 to 2000] encoding bitrate for video
--sharpness,-S [0 to 2] sharpness of images(default 2)
{ lower values make the video sharper. }
--keyint,-K [8 to 65536] keyframe interval (default: 64)
--audioquality,-a [-1 to 10] encoding quality for audio
--audiobitrate,-A [45 to 2000] encoding bitrate for audio
--samplerate,-H set output samplerate in Hz
--channels,-c set number of output sound channels
--nosound disable the sound from input
--endtime,-e end encoding at this time (in sec)
--starttime,-s start encoding at this time (in sec)
--v2v-prwww-data,-p encode file with v2v preset,
right now there is preview and pro,
'ffmpeg2theora -p info' for more informations

Input options:
--deinterlace,-d force deinterlace,
n otherwise only interlaced material is deinterlaced
--format,-f specify input format
--inputfps [fps] override input fps

Metadata options:
--artist Name of artist (director)
--title Title
--date Date
--location Location
--organization Name of organization (studio)
--copyright Copyright
--license Licence

Other options:
--nice set niceness to n
--debug output some more information during encoding
--help,-h this message

Examples:
ffmpeg2theora videoclip.avi (will write output to videoclip.avi.ogg)

cat something.dv | ffmpeg2theora -f dv -o output.ogg -

Live encoding from a DV camcorder (needs a fast machine)
dvgrab - | ffmpeg2theora -f dv -x 352 -y 288 -o output.ogg -

Live encoding and streaming to icecast server:
dvgrab --format raw - | \
ffmpeg2theora -f dv -x 160 -y 128 -o /dev/stdout - | \
oggfwd iccast2server 8000 password /theora.ogg

Plugging in

Now, turn on the camera. Check the raw1393 module is loaded by using lsmod (see the section near the beginning of this document on raw1394).

ok, so the thing is you will need know is to execute the following line on one command line. You will need to use the streaming server details you have for the Icecast2 (theora-enabled) server. The command is:

dvgrab --format raw - | ffmpeg2theora -a 0 -v 5 -f dv -x 320 -y 240 -o /dev/stdout - | 

oggfwd  icecastserver  8000 pwd /theora.ogg

Remember the command will have to be all on one line (the above example is not). Also replace the details:

• icecastserver
• 8000
• pwd

with the details you have from your Icecast server. icecastserver should be replaced with the hostname or IP address of the streaming server. 8000 is the port number and is probably the same. pwd should be replaced by the password of your server. Lastly, you can replace /theora.ogg with anything as long as it starts with a forward slash (/) and ends in .ogg.

Now, you should be streaming! To check the connection use VLC .

Streaming Ogg Theora with VLC

Software name : VLC
Software version  : 0.8.6b 
Hardware Requirements : internet connection, 300 MHz computer
Software Requirements : for Linux you need automake version 1.9 or greater, libtool, libtheora, libshout, g++, gettext, libgcrypt and wxwidgets or qt4 installed, access to an Icecast server

vlc can now stream theora to icecast2. Doing this with Windows isn't that tricky. However, if you wish to do this with Linux you will need to have some experience installing software from the command line. 

Streaming Server Requirements

We will look at streaming to an Icecast Server. To do this you need access to an Icecast Server or someone needs to create you an account and give you the access details. You need to know the following details about the Icecast Server :

• Hostname or IP Number of the Icecast Server
  
• Port (default is 8000)
  
• Password 
• Username (this may not be necessary depending on how Icecast is configured)
  
• Mountpoint (this may not be necessary depending on how Icecast is configured)

Preperation (Linux)

I installed the source code version of vlc using a clean (new) Debian 4.0 (r0). Please note : this process can take a while and its not straight forward. Compiling vlc can be tricky and it very well may not follow exactly what see here (depending on what you have installed on your computer). Additionally the compiling itself (running make) can take a while even on fast machines. Beware! 

You will need automake version 1.9 or greater. To find out if this exists type 'automake --version' in your terminal. If you get an error, then its not installed, if it reports that the version number is less that 1.9 then you need to upgrade.

To test for libtool try typing 'libtool --version' in the terminal, if you see an error then its not installed and you will first need to install it.

To test for gettext type 'gettext --version' in the terminal, if you get an error then its not installed and you need to install it.

To test for g++ type 'g++ --version' in the terminal, if you get an error then its not installed and you need to install it.

Additionally libgcrypt needs to be present. To test if you have it installed already try the command 'whereis libgcrypt' in the terminal. if you don't get some files listed it isn't installed. (Debian users install libgcrypt11).

Additionally libtheora needs to be present. To test if you have it installed already try the command 'whereis libtheora' in the terminal. if you don't get some files listed it isn't installed. (Debian users install libtheora).

Check for libshout by typing 'whereis libshout' if you get no feedback then find it and install it. You also need the header files for libshout (Debian users install libshout3-dev).

To check if wxwidgets is installed type 'wx-config' in the terminal, if you get an error that the command does not exist then install it (Debian users install libwxgtk2.6-dev). Alternatively you can use qt4 (these libraries are for the graphic user interface) but if you do this you are on your own as we will follow the wxwidgets route here .

Now download the latest sources from http://www.videolan.org/vlc/download-sources.html

Now you will need to untar the source file, at the time of writing the sources are 0.8.6b, so type the following

tar zxvf vlc-0.8.6b.tar.gz

Next you will need to cd to the newly created directory.

cd vlc-0.8.6b

Installation (Linux)

Next you need to run the configure script with the right parameters.

If you have decided to compile wxwidgets then you need to include --enable-wxwidgets. If you are using the qt4 interface then VLC now detects this by default so no parameters are needed. Additionally you require the --enable-shout parameter, otherwise the shoutcast module won't be installed and you won't be able to stream.

You could then just run the configure script with these parameters but you will probably come up with some errors. I did this several times and when an error appeared in the configure process I looked at the error message and then tried to work out what software was missing and disbaled it with another parameter. I had to disable libmad (--disable-mad) as it wasn't installed. Additionally I had to use --disable-a52 and --disable-ffmpeg and --disable--libmpeg2 and --disable-glx. All my libraries are located under '/usr' not '/usr/local' so I had to also include the --Prefix=/usr parameter. So my complete command line configure script execution looked like this  

./configure --enable-shout --disable-mad --disable-a52 --disable-ffmpeg 
     --disable-libmpeg2 --disable-glx --enable-wxwidgets --enable-theora --prefix=/usr

The above command would have to all appear on one line in your terminal. Next, if your configure process goes smoothly with no more errors, try the make command.

make

The build will take a while even on a fast machine so go and get a coffee. If it is successful then type:

make install

The only trick here that I know of (and there maybe others) is that if you don't have g++ installed you won't get any errors compiling vlc but the interface won't compile and you will end up with a command line only version. If this happens and you want vlc with a graphic interface, then check you have g++.

Check Shout Module is Installed (Linux)

If you are using Linux you will need to double check the shout module is installed before you progress. To do this type the following into a terminal:

vlc -l | grep shout

If all is well you will see something like the following in the terminal window:

VLC media player 0.8.5 Janus
  access_output_shout   IceCAST output
  playlist              New winamp 5.2 shoutcast import
  shout                 Shoutcast radio listings

The important part of the above output is the access_output_shout IceCAST output. This means you have the right module available for streaming to an Icecast Server. If you don't have this module you are going to have to read up on how to install it. Note :  It might be that the Shout libraries store the shout.h file in the wrong place, this is a bug in the latest versions of Shout. To work around this, you may need to re-compile VLC but before doing so edit the file shout.c file in the VLC sources. This file is located here:

modules/access_output

you will need to edit this line:

#include <shout/shout.h>

to this:

#include <shout.h>

Check Shout Module is Installed (Windows)

To check if the Shout Module is installed on Microsoft Windows you will need to open the Preferences window from the Settings menu:

The preferences interface will open:

Now click on the tiny "+" next to Stream Output :

You will get a drop down menu:

Click on the "+" next to Access output and with luck you will see something like this:

Notably, there will be an item labeled Shoutcast. If you don't see this then the Shoutcast module is not installed. If it is not installed then try downloading the latest installer and install VLC again. If you do see it then you should be able to stream to Icecast. Clicking on the Shoutcast icon should show you something like this:

Choosing Video File to Stream 

You can stream audio or video with VLC to Icecast. However this has variable results depending on what operating system you are using. For now we will look at streaming an ogg theora video file. The first thing you need to do of course is open  VLC. Now from the File menu choose Open File

This will open a file browser so you can browse (click the Browse button) through your harddisk and choose a video file to stream.

Press the Open button at the bottom right. When you have done this there should be the title and location of your chosen file displayed in the interface:

Stream Settings

Now click on the Stream/Save check box:

This should then make the Settings... button clickable:

Now click the Settings... button and you should see something like this:

This is the configuration window for your stream. It might look complicated, and truth be told, it is! However we can go through this process quickly to configure and outgoing audio stream to an Icecast Server. The way that VLC works with outgoing streams is by creating what the good people at Videolan call an output chain. An output chain is a rather complicated way of referring to the the process of configuring VLC so that it streams. 

Unfortunately VLC doesn't (yet) incorporate a handy GUI (Graphical User Interface) for doing this. GUIs are much easier if you aren't used to configuring software using command line interfaces (CLI). We can get some of the way to configuring our stream settings through the interface but the rest will have to be typed into the Stream Output MRL at the top of the above dialog.

First of all, click on the HTTP check box in the Outputs section of the window:

When checked you will see two things happen, firstly the information to the right of the check box will allow you to input data:

The other thing you will see is that the Stream output MRL box will display some information:

The above information is what we need to tweak to make VLC stream and to do this you will need to alter the information in this text box using the Icecast Server details you should have.

Entering Server Information

In the above example the following information is shown in the Stream output MRL:

:sout=#duplicate{dst=std{access=http,mux=ts,dst=:1234}}

We need to alter this information to reflect the details you have of your streaming server (Icecast). You should have the following details:

• Hostname or IP Number of the Icecast Server
  
• Port (default is 8000)
  
• Password 
• Username (this may not be necessary depending on how Icecast is configured)
  
• Mountpoint (this may not be necessary depending on how Icecast is configured)

These need to be incorporated in the  Stream output MRL box as follows:

:sout=#duplicate{dst=std{access=shout,mux=ogg,dst=username:pass@hostname:port/mountpoint}}

Notice that the two following settings are also important to check if they are correct:

access=shout

mux=ogg

For example, lets say I had the following details:

• Hostname : icey.me.net
  
• Port : 8000
  
• Password : floss
• Username : streamer
  
• Mountpoint : live

Then the Stream output MRL would read as follows:

:sout=#duplicate{dst=std{access=shout,mux=ogg,dst=streamer:floss@icy.me.net:8000/live}}

There are a couple of things to note here. First, with Icecast you don't always need a username to stream. If you are in this situation then use "source" in the text above where the password should be. For example, the text in the Stream output MRL would be something like:

:sout=#duplicate{dst=std{access=shout,mux=ogg,dst=source:floss@icy.me.net:8000/live}}

Also, if you haven't been given a mountpoint you can usually make one up but don't use any special characters in the text, and if you haven't been given a port then try the default 8000.

Start Streaming 

All that is left to do is to press the OK button at the bottom of the window, you will be returned to the previous window:

Now you are almost ready to stream. Press OK again, and you should start streaming. VLC provides minimal feedback to let you know how things are going, but if all is ok, you should check your streaming server status page, or try and connect to your stream.

Streaming Live Video (Linux)

v4l:/dev/video:input=2:norm=palize=192x144 –sout \
‘#transcode{vcodec=theora,vb=300,acodec=vorb,ab=96}td{access=shout,mux=ogg,url=iceyserver.com:8000} 

you can replace localhost:8005 with your details 

Cortado

Using Cortado

<html>
  <head>
  </head>
  <body>
    <applet code="com.fluendo.player.Cortado.class" archive="cortado.jar" 
		width="352" height="288">
      <param name="url" value="http://myserver.com/theora.ogg"/>
      <param name="framerate" value="29"/>
      <param name="keepAspect" value="true"/>
      <param name="video" value="true"/>
      <param name="audio" value="true"/>
      <param name="bufferSize" value="100"/>
      <param name="userId" value="user"/>
      <param name="password" value="test"/>
    </applet>
  </body>
</html>

<param name="url" value="http://myserver.com/theora.ogg"/>

Jorbis 

jcrafts java streaming server, supports theora
http://www.jcraft.com/jorbis/

installation using JOrbis 0.0.15
compiling

~/src/jroar$ javac com
/jcraft/jroar/JRoar.java

playlist

~/src/jroar$ find /var/mp3/ -name "*.ogg" -print > /tmp/foo

running

~/src/jroar$ java com.jcraft.jroar.JRoar -port 9000 -playlist /test1.ogg /tmp/foo

Joining two Ogg Theora Files

If you want to quickly join two Ogg Theora video files then you can simply use the Linux command cat

cat

cat file1.ogg file2.ogg > output.ogg

A word of warning about this method : this may not work for replaying the joined file with some players. The problem is that this is not the right way to do it. Its a quick hack that might work. The reason it might not work for some players is that Ogg Theora video files have timestamps in them and some players rely on these timestamps so they can replay the content properly. If you just join the files using cat then the timestamps are not correctly altered and the players may throw errors. So check it before you come to rely on it.

Ripping a Theora Stream

If you are running Linux it is easy to rip an Ogg Theora stream. This is because Theora uses HTTP to stream, hence you can use wget like so:

wget http://streamingserver:8000/streamname

For example, if the server was icecast.streamingsuitcase.com and the stream name was theora.ogg I would use the following command for archiving:

wget http://icecast.streaminguitcase.com:8000/theora.ogg

This is good but if wget buffers it will quit the archiving. However you can try this:

while true; do wget http://icecast.streaminguitcase.com:8000/theora.ogg;done

Another bonus from using wget to archive is that it will increment the file names. So if you archive the stream in the example above the file would be saved as theora.ogg if you stopped wget and started it again the next file would be called theora.ogg.1 etc. This means you don't overwrite the existing archive file.

More Help

For more help with TheoraCookbook you can try these avenues:

TheoraCookbook Documentation 

should first look at the very good documentation at the developers site:

Online Forums 

You can also try searching through the forums for information.  

The forums contain a lot of postings from users on many topics. You can use the search system to locate topics or just browse the categories. If you don't find what you want then try subscribing to the forums and posting your question to the relevant category. There are a few things to keep in mind when asking a question in a forum or to a mailing list. First, be as clear as you can with your question and provide any infromation that you might think would help some to try to help you. You might, for example, include information about the operating system you are using, or various specifics that relate to what you are terying to achieve. Additionally, it is always good practice to also post back to any forum or mailing list if you manage to solve your query and include clear information on how you solved the puzzle. This is so that someone else that may have the same issue can resolve it using what you have found out. If possible post back to the same thread (discussion topic) so tha tanyone searching through the forum can follow the discussion including the solution.

Web Search

Searching the web is always useful. If you are looking for problems arising from errors reported by the software then try entering the error text into the search engine. Be sure to edit out any information that doesn't look generic when doing this. Some search engines also enable you to try searches of mailing lists, online groups etc, this can also provide good results.

Mailing Lists

Mailing lists are good places to look through for answers to questions. The archives are located here :

You can also subscribe to the mailing lists and ask a question:

Please note the suggestions about posting to forums and mailing lists in the above section.

IRC

IRC is a type of online chat. it is not the easiest to use if you are not familair with it but it is a very good system. There are a variety of softwares for all operating systems that enable you to use IRC. The IRC channel for VLC is where a number of the developers are online and some 'superusers'. So logging into this channel can be useful but it is very important that you know exactly what you are trying to find out before trying this route. The protocol for using the channel is jus tot log in, and ask the question immediately. Don't try and be too chatty as you are probably going to be ignored. It is also preferable if you have done some research using the other methods above before trying the channel. The details for the IRC channel are:

• IRC network:
• Channel: #

Glossary

License

All chapters copyright of the authors (see below). Unless otherwise stated all chapters in this manual licensed with GNU General Public License version 2

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this documentation; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Authors

_{Free manuals for free software}

General Public License

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS