README.debian für Freevo

freevo for Debian
-----------------

Contents:

0.   How freevo is packaged for Debian
0.1 Different usage scenarios
0.2 Some more info
0.3 Upgrades and security
0.4 Extra packages
1.   Configuring freevo
1.0 Xserver resolution
1.1 Configuring freevo for automatic shutdown/reboot

-----------------

0. How freevo is packaged for Debian

This packaging of freevo was designed so that you will end up using
freevo in a different way than the upstream suggested way.

The main differences are that

- all freevo-related process will not be run as root, but as the
'freevo' user;

- the data is stored in /home/freevo , and not in
   /var/lib/freevo , /var/cache/freevo ....;

- the freevo data has permission -rw-rw-r-- so that all users
in the 'freevo' group can share it (for this reason, we will
call it "shared data" in the following);

- in case the PC has a recording video card, this package contains
/etc/init.d scripts to start a family of system processes, so as to
turn your PC into a fully functional PVR (personal video recorder);

- but the freevo program may also be started by any user logged into
the PC (there is also a menu item for this).

-----------------

0.1 Different usage scenarios

All of the above design choices enable 3 different usage scenarios

    ---- PVR

In this scenario, your PC becomes a fully functional PVR. At boot,
it starts the dedicated freevo xserver (that contains the main GUI -
it is attached to virtual console 9) and the recordserver, and maybe
the encoding server and web server (this latter, so that you may
access your PVR from remote, using a browser). To save money in
electricity bills, you may wish that your PC will shutdown and
reboot automatically to record the shows: you should read section 1.1

    ---- PVR + desktop

In this scenario, your PC is both your PVR and your desktop. In
this case, you should start the recordserver, but not start the
xserver; rather you should add the normal users to the 'freevo'
group, so that they can start the freevo program to access the
shared data, add TV shows to the recording schedule...etc etc.
You may still wish to have freevo automatically shutdown and reboot
(do not forget to set AUTOSHUTDOWN_WHILE_USER_LOGGED=False
in /etc/freevo/local_conf.py ).

    ---- desktop with no video acquisition card

If your PC does not contain a video acquisition card, you can
still use freevo to have a convenient GUI to listen to music, play movies,
view images, etc etc; possibly using a remote.

-----------------

0.2 Some more info

Let us elaborate a bit more.

When you install the freevo Debian package (hereafter referred to as
"freevo .deb"), an user 'freevo' is created, and a group 'freevo' as
well. The user 'freevo' has home directory /home/freevo .

You should add normal users to the 'freevo' group:
in this way, they will share all the data, that is,
audio, video and images, as well as the recording schedule,
and in particular, the cache, that ends up being quite large
and quite long to regenerate (~40 minutes in my box).

When you have installed freevo, there were many debconf
questions (the number is depending on your debconf setting).
If you did not change the default directories, then all data related
to freevo will be stored inside /home/freevo . For example, the
default video directory is /home/freevo/video/ .

To find out the chosen directories , read the config files
/etc/default/freevo
that you may edit at your wish, and also
/etc/freevo/debconf.sh   /etc/freevo/debconf.py
that are automatically generated, (if you wish to change
the settings in these two latter files, run
dpkg-reconfigure freevo
as root).

Any data you put in the default directories will appear in the
GUI to any user that is in the 'freevo' group and starts freevo.

-----------------

0.3 Upgrades and security

The freevo services are not (re)started or stopped when you
install/upgrade/remove the freevo .deb.
There are many reasons for that:
- starting the xserver on install will switch to a different console,
and this may confuse people;
- if the recordserver is recording, and the sysadmin updates
the freevo .deb, and this automatically restarts the server,
then the recording would be lost.

For this reason, when you upgrade the .deb, you should
restart the services manually,
[TODO] until we find a better solution (idea: do as gdm does ?).

-----------------

0.4 Extra packages

To properly work, some freevo plugins need extra packages, that are
listed as "Recommends" and "Suggests" by the freevo .deb . Those
listed as "Recommends" are in the main Debian repository. Some of
those listed as "Suggests" are not (currently) available in the main
Debian repository.

For example
msttcorefonts
is available in the 'contrib' section of Debian ; whereas
mencoder, lame, libdvdcss2
are not in Debian, but may be found in www.debian-multimedia.org
(thanks to Christian Marillat).

'mencoder' is needed if you have a cheap video card that does not
encode video in hardware, then you need 'mencoder' to compress the raw
video on the fly before storing it to hard disk (why? because the raw
video would fill your hard disk in minutes) - note that in this
case you need a very fast CPU.

'mencoder' is also used by the encodingserver.

'libdvdcss2' is needed to play encrypted DVDs (that is, almost all DVDs)

Note that the packages 'mencoder' and 'lame' contain code that implements
patented algorithms , and it may be illegal in some countries to use
them w/o paying royalties and such.

(Don't ask me why libdvdcss2 may be considered illegal, even when used
to view a legally purchased DVD... this fact beats me).

--------------

1. Configuring freevo

To configure freevo, you should read the documents in
http://doc.freevo.org/Configuration

There are though some Debian specific points to clarify.

The 6 files for configuring freevo are
/etc/freevo/freevo.conf
/usr/share/freevo/freevo_config.py
/etc/freevo/local_conf.py
/etc/default/freevo
/etc/freevo/debconf.sh
/etc/freevo/debconf.py
note that the last 3 are Debian specific.

The freevo .deb, when installed, puts the file local_conf.py.example
file in /etc/freevo/ ; and if the file /etc/freevo/local_conf.py does
not exist, then it creates as a copy of local_conf.py.example .
Moreover the freevo .deb uses the debconf questions to create
/etc/freevo/freevo.conf .

With all the above machinery, after you install the .deb you can
readily start the freevo program ; but you still need to configure
remote and video card (if any) by yourself, [TODO] until we find out
how to autodetect.

In the .deb, /usr/bin/freevo is actually a wrapper (a shell script).
The python program that is installed as /usr/bin/freevo
by the upstream source code is renamed to /usr/bin/freevo.real

When you start /usr/bin/freevo, this wrapper resets the freevo-related
environment variable, and it sources /etc/freevo/debconf.sh and
/etc/default/freevo (setting some freevo-specific environmental
variables) ; then the wrapper tries to switch the principal group to the
'freevo' group; eventually the wrapper calls the usual python program
/usr/bin/freevo.real . The python program then uses the environment to
set some fundamental directories , and then it sources
/usr/share/freevo/freevo_config.py , /etc/freevo/debconf.py and
/etc/freevo/local_conf.py , in that order.

If you wish to configure freevo in Debian, you may edit
/etc/freevo/local_conf.py ; moreover , to set any environmental variable,
you may use /etc/default/freevo

-------------

1.0 Xserver resolution

Unfortunately, AFAIK the Xserver does not have a commandline option
to set the desired resolution. So currently the freevo
window will be smaller than the X session. If you
are setting up a PVR, you may edit /etc/X11/xorg.conf
so that the default resolution is the same as the freevo resolution.
TODO: we need a better way to cope with this....

-------------

1.1 Configuring freevo for automatic shutdown/reboot

See the document http://doc.freevo.org/GeneralPlugins/Wakeupshutdown

As explained in the above document, since freevo does not run
as root in Debian, then some action must be taken so that the freevo user
can operate the required commands 'shutdown' , 'halt' and 'nvram-wakeup'
(this latter is in the Debian package 'nvram-wakeup).

One way is to configure sudo, and set
SHUTDOWN_SYS_CMD = 'sudo shutdown -h now'
RESTART_SYS_CMD = 'sudo shutdown -r now'
in /etc/freevo/local_conf.py ,
and something similar for the 'nvram' call

The other way, more Debian specific, is to change the permissions
of the commands, using

$ dpkg-statoverride --update --add root powerdev 4755 /sbin/shutdown
$ dpkg-statoverride --update --add root powerdev 4755 /sbin/halt
$ dpkg-statoverride --update --add root kmem 4755 /usr/sbin/nvram-wakeup
$ adduser freevo powerdev
$ adduser freevo kmem

Moreover , you may wish to set
AUTOSHUTDOWN_WHILE_USER_LOGGED=False
in /etc/freevo/local_conf.py,
to avoid Freevo to shutdown on your face.

-- A Mennucc1 Sat, 9 Feb 2008 20:27:00 +0100