README

= AutoRadio version 3.3 =
https://github.com/pat1/autoradio

OVERVIEW
--------

Radio automation software. Simple to use, starting from digital audio
files, manage on-air broadcasting over a radio-station or
web-radio. The main components are:

    * Player (integrated or external Xmms/Audacious): plays all your media
      files and send digital sound to an audio device or audio server
 
    * Scheduler: real time manager for emission of special audio files
      like jingles, spots, playlist and programs; interact with player
      like supervisor User

    * interface: WEB interface to monitor the player and scheduler and
      admin the schedules for the complete control over your station
      format. The web interface allows you to easily publish podcasts
      that conform to the RSS 2.0 and iTunes RSS podcast specifications
      The web interface provide a "full compatible" ogg player.

Developed with Python, Django, Dbus it works in an production enviroment


FEATURES
--------

 * manage ogg, mp3, and other media file format managed by gstreamer
 * it's designed as client - server
 * manage playlists, inserting on it jingles, spots and programs
 * programmable rules for schedule and period schedule
 * do not overlap schedules: anticipate, postone or delete
 * player is monitored by web interface
 * spots are grouped and ordered by your preference
 * programs are available for podcasting in a very complete rss feed web interface
 * integrated web player for ogg vorbis that is very compatible with most user's systems
 * can produce a palimpsest and a printable version is available following the the italian law standard
 * integrated daemon system with logging
 * provide enhanced version of dir2ogg.py and mkplaylist.py to manage
   files with music (convert to ogg and make playlist)
 * do not use DataBases to manage music; you can use your preferred application to produce playlists  
 * on line web documentation

REQUIRES
--------

autoradio requires:

python >= 3.7

mutagen
muatgen version >= 1.17
http://code.google.com/p/mutagen/

django
http://www.djangoproject.com/
Suggested Django >= 2.2

configobj
Summary     : Config file reading, writing, and validation
URL         : http://www.voidspace.org.uk/python/configobj.html

gstreamer
Autoradio can use gstreamer 0.10 but is better to use gstreamer 1.0; the installed plugins establish the usable audio formats.

OLD DISTRIBUTIONS
-----------------
Autoradio try to work on very old distribution like fedora 8 with xmms and 
cherrypy2
On not so old distribution try to use audacious version >= 1.5 and cherypy3
python >= 2.5

cherrypy
Summary     : A pythonic, object-oriented web development framework
URL         : http://www.cherrypy.org/
Thera are incompatibility from cherrypy version 2 and 3
but autoradio works well with any version :)

Player (xmms or audacious in alternative):

  for xmms player
    pyxmms
    http://people.via.ecp.fr/~flo/index.en.xhtml

    xmms
    http://www.xmms.org/

  for audacious player version >= 1.5
    dbus-python   D-Bus Python Bindings
    http://www.freedesktop.org/software/dbus/

    audacious
    http://audacious-media-player.org/

the player web server respond on port 8888


HOW TO INSTALL
--------------

>>>>> Easy way:

You can run autoradio daemon and web server from your root software
distributed directory:

python setup.py build

change your preferred language and other preference in autoradio.cfg 

./autoradioctrl --syncdb
You have to answer to some question to setup database.

./autoradioweb run
This start autoradio webserver on localhost port 8080

control+c to stop it
if all works well you can detach it with
./autoradioweb restart

./autoplayerd run
This start the player daemon and you can listen it if you have a sound card and loaded audio files

control+c to stop it
if all works well you can detach it with
./autoplayerd restart


./autoradiod run
This start daemon autoradiod (that in old distribution can launch xmms/audacious ) 

control+c to stop it
if all works well you can detach it with
./autoradiod restart

./autoplayergui
This start the player GUI; with it you can load audio file/playlists and manage audio player


You have to use a browser (on the same machine) pointing to http://localhost:8080


>>>>> Installed way:

you need access to root administrator user and after:

python setup.py install

choose a normal user to run the daemons and create it and login,
make and go in your preferred user working writable directory

modify /etc/autoradio/autoradio-site.cfg or from the normal user
copy it in your working directory with name autoradio.cfg and modify it
specify your personal settings for installed files
if you want you can set user's global settings coping configuration file in
~/.autoradio.cfg

after from root:

autoradioctrl --syncdb --changeuser
autoradioweb restart

You can run autoradiod and autoplayerd in one host and autoradioweb in
other if you use server Data Base like mysql and specify it and where
autoradiod is running in the autoradio configuration (.cfg) files.
The /usr/share/autoradio of the machine where run autoradioweb will be
accessible read (and write) from machine where run autoradiod.  In
addition to do this you have to have a tcp enabled version of dbus
running autoradiodbusd somewhere.

On machine where you want run autoradiod (the player side), after autoradio
installation, from root user create a new user and set password and activate
interactive login like this:
useradd autoradio
passwd autoradio
usermod -s /bin/bash autoradio

login in autoradio user in a X (graphics) session and:
autoradiod run
or
autoradiod restart

For a pubblic web server do not use django internal web server:

autoradioweb stop

but use apache instead:
https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/
you can find an example configuration file in doc directory:
doc/apache_modwsgi_example.conf

set
SERVE_STATIC=False
in /etc/autoradio-site.cfg

>>>> Pachaged way:

for Fedora Centos and Debian/Ubuntu you have the possibility to install from
pachages in a easy way.

For Debian/Ubuntu you can find autoradio in standard distribution.

For Fedora use copr repo at
https://copr.fedorainfracloud.org/coprs/pat1/autoradio/

The pachage create the autoradio user for you and set everything in a
standard way for an easy use.

To start everythings from root user (prepend sudo command for Ubuntu):
autoradioctrl --syncdb --changeuser
autoradioweb restart

You can run autoradiod and autoplayerd in one host and autoradioweb
in other if you use server Data Base like mysql and specify it and where
autoradiod is running in the autoradio configuration (.cfg) files.
The /usr/share/autoradio of the machine where run autoradioweb will be 
accessible read (and write) from machine where run autoradiod.

On machine where you want run autoplayerd (the player side), after autoradio
installation, from root user create a new user and if you want activate
interactive login like this:
useradd autoradio
passwd autoradio
usermod -s /bin/bash autoradio

login in autoradio user in a X (graphics) session and:
autoradiod run
or
autoradiod restart

If you want you can activate monit daemon to control autoradio
daemons; an example conf file to add to monit is in:
doc/monit_autoradio_example.conf

For a pubblic web server do not use django internal web server:

autoradioweb stop

and use apache instead:
http://docs.djangoproject.com/en/dev/howto/deployment/modpython/#howto-deployment-modpython
you can find an example configuration file in doc directory:
doc/apache_mod_python_example.conf

set
SERVE_STATIC=False
in /etc/autoradio-site.cfg

HOW IT WORKS
------------

In player's playlist you need a queue of media for a minumun of some
hours and for this you have to program some playlist.  Player cannot
stay stopped or paused (if stopped it will be started, if paused it
stay paused) for a corret work.  When time will be right jingle,
programs and spots will be placed in playlist the first position after
the last file inserted before by autoradiod

HOT TO USE IT
-------------

autoradioctrl provide some administration commands like --sincdb to
inizialite the data base.

autoradioweb or other web serber like apache provide a web interface
to program every thinks you cannot find in configuration files; you
have to run it like a permanent daemon; use a browser pointing it at
the machine and port of the web server (http://localhost:8080 is the
default for autoradioweb).

Run autoplayerd to start to play music. You need an audio card.

You can run autoradiod to start the automation of the player;
autoradiod manage the player with the programmed schedules.  You can
run autoplayerd/autoradiod from the same machine where run
auroradioweb; it use sqlite local file. If you use a database
client/server like mysql you can access the DB from an other machine
but you have to read the media files from all machines involved (with
nfs services).

Where you have an X server you can run autoplayergui to interact with
graphical interface with the player.

Read doc/user_guide.txt or the documentation in the web admin
interface for the features enabled in the autoradio suite.

CONTRIBUTED SOFTWARE
--------------------

module daemon come from http://www.livinglogic.de/Python/index.html
## Copyright 2007-2009 by LivingLogic AG, Bayreuth/Germany.
## Copyright 2007-2009 by Walter Dörwald
## OSI Approved :: MIT License

module mkplaylist come from http://bj.spline.de/mkplaylist-man.html
# Author:        Marc 'BlackJack' Rintsch
# Copyright:     (c) 2004-2009
# Licence:       GPL

module dir2ogg come from http://jak-linux.org/projects/dir2ogg/
# Copyright (C) 2007-2009 Julian Andres Klode <jak@jak-linux.org>
# Copyright (C) 2003-2006 Darren Kirby <d@badcomputer.org>
# Licence:       GPL

django-podcast  http://code.google.com/p/django-podcast/
                https://github.com/jefftriplett/django-podcast
#  Copyright (c) 2008, django-podcast Project Members
#  All rights reserved.
#
#  Redistribution and use in source and binary forms, with or without
#  modification, are permitted provided that the following conditions
#  are met:
#
#    * Redistributions of source code must retain the above copyright
#      notice, this list of conditions and the following disclaimer.
#    * Redistributions in binary form must reproduce the above
#      copyright notice, this list of conditions and the following
#      disclaimer in the documentation and/or other materials provided
#      with the distribution.
#    * Neither the name of the django-podcast Project nor the names of its
#      contributors may be used to endorse or promote products derived
#      from this software without specific prior written permission.
# 
#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
#   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
#   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
#   FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
#   COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
#   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
#   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
#   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
#   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
#   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
#   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
#   OF THE POSSIBILITY OF SUCH DAMAGE.

SWFObject v2.2 
  <http://code.google.com/p/swfobject/>
  is released under the MIT License 
  <http://www.opensource.org/licenses/mit-license.php> 

jQuery JavaScript Library v1.4.1
  http://jquery.com/

  Copyright 2010, John Resig
  Dual licensed under the MIT or GPL Version 2 licenses.
  http://jquery.org/license

  Includes Sizzle.js
  http://sizzlejs.com/
  Copyright 2010, The Dojo Foundation
  Released under the MIT, BSD, and GPL Licenses.

  jquery Open Window plugin
  http://plugins.jquery.com/project/open
  GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007

Cortado - a video player java applet
  Copyright (C) 2004 Fluendo S.L.

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

anoggplayer
  http://code.google.com/p/anoggplayer/
  GNU LESSER GENERAL PUBLIC LICENSE

fogg
  http://bazaar.launchpad.net/~arkadini/fogg/trunk
  GNU LESSER GENERAL PUBLIC LICENSE

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

Italiano:

Autoradio è una suite di programmi che partendo da file audio digitali
permette la gestione automatica dell'emissione di una stazione
radiofonica.

queste sono le componenti:

    * Player: partendo da una playlist è in grado di gestire
      differenti formati di audio digitali per poi inviare il suono o
      a una scheda audio o a un server audio

    * Scheduler: gestisce in tempo reale l'emissione di particolari
      file o audio quali i jingles, pubblicità, playlist e programmi;
      interagisce col player controllandolo e impartendo comandi

    * L'intefaccia utente: utilizzando una interfaccia WEB pemette il
      monitoraggio dello scheduler e del player e permette la
      programmazione del palinsesto. L'interfaccia web permette anche
      di pubblicare facilmente podcasts conforme alle specifiche RSS
      2.0 e iTunes RSS.