Soma Suite 1.2

Andrea Marchesini <bakunin@autistici.org>

14 giugno 2004

Abstract

La suite Soma  una collezione di tre applicativi per 
la gestione del palinsesto di una radio. Un demone 
chiamato somad gestisce le trasmissioni utilizzando 
come input file audio in locale o in streaming passati 
poi un un player esterno (vedi somaplayer) e 
amministrando stacchi pubblicitari, pause, random e 
molto altro. 

Abstract

Attraverso somaclient, si pu amministrare somad 
runtime via rete modificandogli il palinsesto, 
cambiandolo, stoppandolo e quindi gestendolo in ogni 
suo aspetto.

Abstract

Somacheck controlla la sintassi dei file di 
configurazione necessari per somad.

Abstract

Table of Contents

1 Introduzione
    1.1 Requisiti
    1.2 Installazione
        1.2.1 Simple Mutex
2 Configurazione
    2.1 soma.cfg
        2.1.1 User
        2.1.2 Background
        2.1.3 ServerName
        2.1.4 Port
        2.1.5 Listen
        2.1.6 Password
        2.1.7 Debug
        2.1.8 LogFile
        2.1.9 PathSong
        2.1.10 PathSpot
        2.1.11 ProgramSong
        2.1.12 OptionsSong
        2.1.13 ProgramStream
        2.1.14 OptionsStream
        2.1.15 PathModules
        2.1.16 Palinsesto
    2.2 palinsesto.cfg
        2.2.1 Palinsesto
        2.2.2 Description
        2.2.3 Start e Stop
        2.2.4 Type
        2.2.5 Random
        2.2.6 SoftStop
        2.2.7 RatioSong e RadioSpot
        2.2.8 PathSong e PathSpot
        2.2.9 Stream
        2.2.10 Module
        2.2.11 Jingle
        2.2.12 Include
3 Avvio
    3.1 Somacheck
    3.2 Somad
    3.3 Somaclient
        3.3.1 --server e --port
        3.3.2 --password
        3.3.3 --readdirectory e --readpalinsesto
        3.3.4 --filepalinsesto
        3.3.5 --oldpalinsesto
        3.3.6 --getpalinsesto
        3.3.7 --nextsong
        3.3.8 --status
        3.3.9 --running
        3.3.10 --quit
        3.3.11 --stop e --start
        3.3.12 --code
        3.3.13 -pPASSWORD
        3.3.14 Shell mode
    3.4 Altri software
4 Struttura di una radio
    4.1 Primo esempio
    4.2 Secondo esempio
    4.3 Terzo esempio
5 Moduli
    5.1 Programmazione di moduli
        5.1.1 soma_pl
    5.2 Esempio
6 Conclusione



1 Introduzione

Quello che segue  il manuale di installazione e 
utilizzo della suite soma. Spero di essere abbastanza 
chiaro e di non dimentarmi niente :) Se qualcuno trova 
qualche passaggio errato o poco approfondito  pregato 
di scrivermi.

1.1 Requisiti

Soma  installabile su quasi la totalit delle 
architetture e su quasi su qualsiasi sistema operativo 
(windows compreso: cygwin docet). I requisiti sono:

* libreadline - utilizzo 'intelligente' del terminale 
  http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html

* libncurses - grafica di terminale 
  http://www.gnu.org/software/ncurses/ncurses.html

1.2 Installazione

La suite soma  scaricabile dal sito internet 
http://soma.realityhacking.org e, nel momento della 
scrittura di questo documento, l'ultima versione 
rilasciata  la 1.2:

http://soma.realityhacking/src/soma-1.2.tar.gz

La procedura di compilazione  quella standard:

./configure

consiglio sempre di vedere le optioni del configure:

./configure --help

Poi si compila con:

make

e si installa con:

make install

Quest'ultimo comando  da farsi come root.

1.2.1 Simple Mutex

E' probabile che su certe architetture somad non 
compili. Questo capita perch i mutex che utilizza 
somad per gestire i suoi thread e l'accesso di questi 
alla zona di memoria condivisa del software non sono 
quelli standard posix (pthread o nptl), ma li ho 
scritti io. 

E' un progetto sviluppato da me anni fa chiamato SM 
(simple mutex). Una implementazione degli algoritmi 
mutex, variabili condizionali e altro con una 
attenzione maggiore agli errori e al carico di CPU. Li 
ho scritti per le principali architetture di cui 
conosco l'assembler, ma la compilazione a volte 
fallisce per la mancanza di riconoscimento dell'architettura.

Per risolvere questo problema bisogna sapere che 
architettura si possiede (i386, ppc, alpha, m68k, mips, 
sparc) e dopo di che effettuare il configure settando 
la variabile CFLAGS in maniera opportuna aggiungendo 
-d<architettura>. Esempi:

-dppc o -dalpha o -dsparc

Quindi il comando da far per configurare correttamente 
la suite soma in fase di compilazione :

CFLAGS="-Dppc" ./configure

e poi si continua con make e make install.

2 Configurazione

La suite soma, come detto nell'abstract  composta da 3 
applicativi separati:

* somad - il demone di scheduling del palinsesto

* somaclient - il gestore del demone

* somacheck - controllore dei file di configurazione

Per poter quindi lanciare ed utilizzare somad  
necessario prima di tutto scrivere in maniera corretta 
2 file di configurazione:

* /etc/somad/soma.cfg - configurazione del demone

* /etc/somad/palinsesto.cfg - palinsesto iniziale del demone

Se avete fatto una installazione corretta, dentro la 
directory /etc/somad dovreste gi trovare due file di esempio.

2.1 soma.cfg

Il file soma.cfg  quello che contiene tutti i 
parametri di avvio del demone. Sono quei flag che il 
software va a leggere all'avvio e che non si possono 
pi modificare a meno di chiudere e riaprirlo. Ecco 
cosa pu contenere il file soma.cfg:

* User = utente con cui il demone deve girare

* Background = se il demone deve girare in background o no

* ServerName = se deve bindarsi su una specifica 
  interfaccia di rete

* Port = ascoltare su una porta diversa da quella standard

* Listen = numero di client che possono amminsitrarlo 
  in contemporanea

* Password = password di accesso alla configurazione

* Debug = livello di debug

* LogFile = in quale file deve scrivere il log

* PathSong e PathSpot = files e streams da mandare 
  sempre (spiegato meglio in seguito)

* ProgramSong = il programma da eseguire per ogni file 
  input audio selezionato dal palinsesto

* OptionsSong = i parametri da dare al programma per i 
  file audio

* ProgrammaStream = quale programma gestisce gli streaming

* OptionsStream = i parametri di quest'ultimo programma

* PathModules = la directory dei moduli

* Palinsesto = il file di palinsesto

E' possibile effettuare commenti attraverso il 
carattere '#', ma anche con i metodi standard del C:

// commento tutto a fine riga

/* commento tutto fino al carattere */

2.1.1 User

Somad, come ogni demone serio :), gira con un utente 
impostato e non per forza come chi l'ha lanciato se ha 
la possibilit di cambiarselo (e solo il root ha questo 
privilegio). Io consiglio di creare un utente apposito 
per far girare somad, solamente per avere maggior 
sicurezza. La sintassi :

User = bakunin

Se non si imposta l'utente somad gira con i privilegi 
di chi l'ha lanciato.

2.1.2 Background

Se si abilita il background, somad si demonizza in 
background. Attivare questa opzione o no  utile per il 
debug. Se non si mette in background infatti, somad 
scrive tutto il debug a schermo e lo si pu analizzare 
al volo. Viceversa utilizza il file di log impostato 
attraverso LogFile. Sintassi:

Background = false

Background = true

Se non lo si imposta di default Background  messo a false.

2.1.3 ServerName

Con servername si pu impostare l'interfaccia di rete 
sul quale somad si binda. Se lo si binda su una 
determinata interfaccia, l'amministrazione pu passare 
soltanto da questa. Se non lo si imposta, somad 
permette l'amministrazione da qualsiasi interfaccia:

ServerName = 127.0.0.1

2.1.4 Port

L'amministrazione da parte di somaclient avviene 
attraverso tcp/ip. Oltre ad un IP serve quindi una 
porta su cui collegarsi. Somad usa come default 12521, 
ma si pu modificare con questa opzione e questa sitassi:

Port = 12345

2.1.5 Listen

Quante connessioni di amministrazione possono avvenire 
in contemporanea? Il default  5:

Listen = 1

2.1.6 Password

L'accesso al server somad avviene tramite 
autenticazione. La password la si imposta qui. Se non 
lo si fa... lo si pu amministrare senza password (da 
leggersi come male).

Password = "ciao"

2.1.7 Debug

Esistono tre livelli di debug:

* 0 - disattivato

* 1 - soltanto gli errori

* 2 - errori e warning

* 3 - di tutto e di pi

Consiglio per i primi test di provare con un debug alto (3).

Debug = 3

2.1.8 LogFile

Qual  il file su cui loggare? Lo si imposta con questa voce:

LogFile = "/var/log/soma.log"

2.1.9 PathSong

Abbiamo detto che nel file soma.cfg esiste l'elenco di 
tutto quello che non si pu pi cambiare se non con un 
riavvio dell'applicativo. I file audio o gli streams 
sono impostati quindi non in questo file ma nel file di 
palinsesto, perch  importante poterli modificare ogni 
volta che si vuole.

Il fatto che dentro il file soma.cfg stia quindi una 
voce per contenere streams e files ha un significato 
diverso: qui bisogna mettere tutto quello che si sa gi 
si mander a priori del palinsesto. Parlo dei jingle 
della radio, delle canzoni di particolare significato, 
di spot pubblicitari di carattere non commerciale, ...

Se si imposta un qualcosa in questo flag, ad ogni 
palinsesto si aggiunge il contenuto di questa variabile 
senza dovere specificare niente.

PathSong = {

  "/Directory/e/sottodirectory/",

  "/Singolifile.mp3",

  "http://streams.remoti/

}

2.1.10 PathSpot

Somad  capace di schedulare spot pubblicitari e file 
audio. Se con PathSong si impostano i file/stream "normali"
, con PathSpot si impostano gli spot. Anche questi 
possono essere remoti, directory, singoli files. Ogni 
quanto vengono mandati gli spot dipende dal palinsesto. 
Ricordo che PathSpot, come PathSong  un di pi 
rispetto al reale corso del palinsesto.

PathSong = {

  "/Directory/e/sottodirectory/",

  "/Singolifile.mp3",

  "http://streams.remoti/

}

2.1.11 ProgramSong

Quale programma esterno devo usare per eseguire i 
file/stream selezionati? Attraverso ProgramSong imposto 
questo elemento esterno. Non bisogna specificare 
nessuna opzione, poich le opzioni si impostano con il 
flag spiegato subito dopo questo.

Qui si pu fare un lungo excursus in favore di certi 
player piuttosto che altri. Fondamentalmente il player 
deve essere un programma testuale poich quelli grafici 
hanno la mania di rimanere aperti anche quando finisce 
il playing del brano. Io ho provato moltissimi player e 
mi sono trovato benissimo con quelli pi piccoli: 
mpg123, mpg321 in primix mi hanno dato molta affidabilit.

Mplayer purtroppo ci impiega troppo ad avviarsi e 
questo fa si che l'ascoltatore finale della radio 
sentir tra un brano e l'altro quel secondo di 
silenzio, a volte fastidioso.

Somaplayer  un player scritto da me. Non mi sembra il 
caso di mostrarvi qui cosa fa, ma vi rimando al sito 
http://soma.realityhacking.org per vedere la 
documentazione proposta. Io utilizzo somaplayer perch 
veloce e in pi, come vedremo in seguito, ha delle 
funzionalit che gli altri player normali non hanno. 
Rimando quindi al capito sui progetti radio.

ProgramSong = "/usr/bin/somaplayer"

2.1.12 OptionsSong

Tutti i parametri da passare al programma da voi 
selezionato con ProgramSong:

OptionsSong = "-ao audio -b 1024k"

Se non si specificano optioni al ProgramSong, vuol dire 
che questo non le avr.

2.1.13 ProgramStream

Esattamente come ProgramSong ma per i programmi che 
somad riconosce come streaming:

ProgramSong = "/usr/bin/somaplayer"

Se non si mette ProgramStream i stream vengono gestiti 
automaticaente con il programma specificato da ProgramSong.

2.1.14 OptionsStream

Tutti i parametri da passare al programma da voi 
selezionato con ProgramStream:

OptionsSong = "-ao audio -b 2048k"

Se non si specificano le optioni al programma per gli 
streams vuol dire che questo non le avr.

2.1.15 PathModules

Somad gestisce moduli caricati runtime. Questa path 
specifica la directory di default per i moduli. 
Parleremo dei moduli in una sezione apposita.

PathModules="/opt/somad/modules"

2.1.16 Palinsesto

Il file di palinsesto di default.

Palinsesto="/etc/somad/palinsesto.cfg"

La prossima parte parler di come si scrive un file di 
palinsesto.

2.2 palinsesto.cfg

Il file di palinsesto  IL file di somad. Mentre 
soma.cfg  un file di configurazione ordinario, 
palinsesto.cfg contiene tutta la struttura delle 
trasmissioni della radio con orari, modalit, 
configurazioni. Questa sezione della documentazione per 
la Suite Soma, va ad analizzare la sintassi di questo 
file. Sar poi nei capitoli successivi che si passer 
al reale utilizzo degli applicativi e quindi si 
spieger come  possibile cambiare da remoto il 
palinsesto, piuttosto che visualizzare informazioni 
sullo stato delle trasmissioni.

Palinsesto.cfg contiene una serie di blocchi Palinsesto 
di questo tipo:

Palinsesto {

  Description = "Trasmissione tipo"

  Start = 1000

  Stop = 1230

  Type = files

  Random = true

  SoftStop = true

  PathSong = {

    "/home/ftp/mp3/jazz",

    "/home/ftp/ogg/jazz/pastorius_jaco_continuum.ogg"

  }

  PathSpot= {

    "/home/spot/",

    "http://www.stream.org/esempio.mp3"

  }

  RatioSong=7

  RadioSpot=2

}

Ognuno di questo riveste una trasmissione. Ogni blocco 
palinsesto pu contenere o no certe voci. Ecco quelle 
supportate da somad:

* Description - la descrizione della trasmissione

* Start - ora di inizio

* Stop - ora di fine

* Type - indica la tipologia di trasmissione

* Random - se i brani devono essere presi random oppure no

* SoftStop - se somad aspetta il termine della canzone 
  prima di effettuare modifiche al palinsesto, 
  spegnimento o altro

* RatioSong - quanti pezzi bisogna mettere prima di 
  mettere degli spot

* RatioSpot - quanti pezzi bisogna mettere di spot 
  prima di tornare alle song

* PathSong - elenco di brani musicali in locale, 
  remoto, o come directory di cui somad prende tutte le 
  sottodirectory.

* PathSpot - elenco di brani di interpretarsi come 
  spot. Esattamente come PathSong possono essere 
  directory, stream e altro.

* Stream - lo streaming da gestire

* Module - che tipo di modulo associare alla 
  trasmissione attuale

* Jingle - il jingle di avvio della trasmissione

* Include - un altro file di configurazione

E' possibile anche in questo file effettuare i commenti 
attraverso i caratteri '#' o con sintassi simili al C:

// commento fino alla fine della riga

/* oppure fino al carattere */

2.2.1 Palinsesto

Ogni sezione di questo file inizia con Palinsesto. 
Possono essere inifiniti e anche scritti in maniera 
disordinata: sar poi somad che li metter in ordine di 
orario per semplificarsi la ricerca e l'accesso ai dati.

La sintassi  quella dell'esempio sopra:

Palinsesto {

  ...altri parametri...

}

2.2.2 Description

La descrizione della trasmissione non  fondamentale, 
ma  altamente consigliata.

La sintassi :

Description = "nome della trasmissione"

2.2.3 Start e Stop

Queste due voci indicano l'orario di inzio e di fine 
della trasmissione. Hanno una sintassi di questo tipo:

HHMM. Quindi se la trasmissione inizia alle 10:00 e 
finisce alle 19:40 si scriver:

Start=1000

Stop 1940

Attenzione a non mettere 0 prima del numero. Ovvero se 
l'inizio della trasmissione  2:15 non bisogna 
scrivere: 0215 ma solo 215. Se si scrive 0215 somad 
interpreta questo valore come ottale :)

Queste voci sono fondamentali.

2.2.4 Type

Il type indica che tipologia di trasmissione stiamo 
descrivendo. Esistono 4 tipologie:

* Files - somad gestisce una playlist di file/stream/directory.

* Stream - somad gestisce uno streaming

* Silence - disattiva questo palinsesto. E' esattamente 
  come non scrivere niente e lasciare un vuoto temporale.

* Module - somad utilizza un modulo esterno. Spiegher 
  meglio cosa si intende per moduli e come si utilizzano.

Di default ogni palinsesto  di tipologia Files.

Files vuol dire che somad considerer le voci PathSong 
e PathSpot, Stream indicher di utilizzare la voce 
stream e Module utilizzer la voce Module.

Type = Files

2.2.5 Random

Se si utilizza come type Files, somad utilizzer questo 
flags per rendere random oppure no la selezione degli 
elementi della playlist. Di default random  
disattivato ma si pu attivare facendo cosi':

Random = true

Questo vuol dire che, tra tutta la playlist legata alla 
singola trasmissione, somad sceglier un brano e lo 
player. Aggiungo che somad  in grado di non 
effettuare ripetizioni ma di gestire il random in 
maniera intelligente. Selezioner un brano gi mandato 
soltanto quando avr mando in onda ogni altro elemento 
della playlist.

2.2.6 SoftStop

Questa voce  di default messa a false, ma si attiva cos:

SoftStop = true

L'attivazione di questa voce rende sensibile somad alla 
durata del pezzo. Mi spiego meglio: essendo somad un 
applicativo,  preciso al secondo sulla gestione delle 
trasmissioni e, se un brano X capita a met tra un 
palinsesto e l'altro, quando  l'ora, somad lo stopper 
per dare spazio alla nuova trasmissione. Se si attiva 
la voce SoftStop, somad prester attenzione a questo 
fatto e aspetter la fine dell'operazione di playing 
per effettuare qualsiasi operazione "drastica" come 
spegnimento, cambio di palinsesto, pausa e altro.

2.2.7 RatioSong e RadioSpot

Di default somad non manda Spot. Ma se si vuole 
mandarli, basta attivare queste due voci. Ogni quanti 
pezzi si manda un brano pubblitario?

RadioSong=5

E di quanti brani  fatto un stacco pubblicatario? 

RadioSpot=2

2.2.8 PathSong e PathSpot

Esattamente come spiegato per il file soma.cfg, con 
queste voci si possono specificare gli elementi di una 
trasmissione di tipologia Files. Si tratta di fare un 
elenco di file locali o remoti e directory:

PathSong = {

  "/home/ftp/directory",

  "/home/ftp/singolo_file.wav",

  "http://qualcosa.remoto.org/file.mp3"

}

Le directory verranno include in ogni sottodirectory.

2.2.9 Stream

Se la tipologia della trasmissione  uno stream, somad 
andr a leggere questa voce e player lo streaming qui impostato:

Stream = "http://radio.streaming.org/radio.mp3"

2.2.10 Module

Se la tipologia di trasmissione  un modulo, qui 
bisogna impostare qual  il modulo da utilizzarsi. 
Somad lo ricercher nella directory dei moduli 
specificata nel file soma.cfg. In un capitolo apposito 
spiegher cosa si intende per moduli, come utilizzarli 
e come scriverli.

Module = "somadiff.so"

2.2.11 Jingle

Ogni trasmissione avr eventualmente un jingle proprio. 
Con questa voce si impone a somad di eseguire quel 
brano (anche remoto) appena si entrer in queste trasmissione:

Jingle=file_trasmissione.ogg

2.2.12 Include

Palinsesto.cfg pu diventare un file molto lungo. 
Attraverso questa voce si dice il palinsesto pu 
continuare anche in un'altro file e quindi si pu 
generare un singolo file per ogni tramissione e 
gestirlo in maniera pi articolata.

Include = "trasmissione1.cfg"

3 Avvio

Nel capitolo precedente abbiamo capito come si scrivono 
i file di configurazione. Ora andiamo a lanciare e ad 
analizzare i programmi della suite uno ad uno.

3.1 Somacheck

somacheck  un applicativo nato per controllare i file 
di configurazione. E' molto semplice da utilizzare ma  
essenziale perche' i file che fanno funzionare somad 
non sono semplici ed  facile dimentarsi un carattere e 
rendere illeggibile tutto. Aggiungo adesso che, somad 
ha bisogno di due file sintatticamente corretti per 
partire. Se questo non avviene, si lamenta notevolmente 
:) Ma nel momento che si decide di caricare un 
palinsesto runtime, somad  capace d i controllare bene 
prima di caricarsi in memoria qualcosa di 
sintatticamente errato e quindi non si blocca se si 
cerca di aggiornare il palinsesto con qualcosa di non 
corretto. Ma anche in questo caso, urla.

Somacheck ha un avvio molto semplice:

* -c o --config per specificare un file di configurazione.

* -p o --palinsesto per un file di palinsesto.

Somacheck controller sintatticamente se tutto  esatto 
e vi dar un responso. Se c'e' qualcosa di errato 
somacheck si dice linea e tipologia di errore riscontrato.

3.2 Somad

A seconda delle scelte che avete fatto nei file di 
configurazione, somad partir in background o no, 
scrivendo dei log a schermo o no, suonando o no.

L'avvio  semplice, non ha infatti bisogno di argomenti 
particolari se i file di configurazione si trovano nel 
posto giusto. Esistono tuttavia degli argomenti 
impostabili a riga di comando:

* -f o --file imposta un file di configurazione diverso 
  da quello standard. Bisogna specificarlo.

* -b o --background manda in background somad anche se 
  nei file di configurazione c' scritto diversamente

* -d o --debug attiva un certo livello di debug

* -u o --user fa si che somad si metta i privilegi 
  dell'utente passato come argomento

Dopo di ch, si lancia:

somad

e si inizia a consultare il file di log.

Una volta lanciato, l'unico modo per chiudere somad 
(ovviamente senza considerare killall -9 o cose di 
questo tipo :),  utilizzare somaclient.

3.3 Somaclient

Lato utente, somaclient  il programma pi complesso. 
Mentre somad  un demone e una volta configurato non ha 
bisogno di particolari ritocchi, somaclient  quello 
che vi permetter di cambiare il funzionamento di somad 
ogni volta ne abbiate bisogno.

E' un programma testuale con molte opzioni e due 
modalit di utilizzo. Si pu utilizzare la linea di 
comando per specificare che cosa si vuole sapere o dire 
a somad, oppure entrare in una modalit shell con la 
quale si pu instaurare una connessione apperentemente 
constante a somad.

Gli argomenti di somaclient sono questi:

* -S o --server imposta qual  il server a cui fare la 
  connessione

* -P o --port la porta del server se non  quella di 
  default (12521)

* -pw -o --password effettua il controllo della 
  password ed esce

* -rd o --readdirectory fa si che somad si rimappi 
  l'albero delle directory impostato nel file di palinsesto

* -rp o --readpalinsesto fa si che somad si rilegga il 
  file di palinsesto

* -fp o --filepalinsesto sostituisce il palinsesto di 
  somad con nuovo specificato

* -op o --oldpalinsesto dice a somad di ritornare al 
  palinsesto originario

* -gp -o --getpalinsesto scrive a schermo il palinsesto 
  che somad sta analizzando

* -ns o --nextsong imposta la prossima canzone da 
  eseguire senza tener conto del palinsesto

* -st o --status informa su che cosa sta facendo adesso somad

* -r o --running informa sullo stato di somad (attivo o no)

* -q o --quit fa chiudere somad

* -1 o --stop stopppa somad. Se si passa un numero come 
  argomento dopo quel numero di secondi somad riparte 
  autonomamente

* -0 o --start fa ripartire somad

* -c o --code fornisce le risposte inviate da somad non 
  informato umano ma sotto forma di codici

* -pPASSWORD fa si che somacliente prenda la password a 
  riga di comando e non chiedendola.

Mentre --server e --port sono necessari per sapere a 
qualche server somad collegarsi, gli altri servono per 
comunicare qualcosa a somad. Se non si mettono 
quest'ultimi, somaclient va in modalit shell. Lo 
spiegher pi avanti.

3.3.1 --server e --port

L'optione -S o --server  necessaria perch indica a 
somaclient a quale somad deve collegarsi. Somad se gira 
su quel computer e se  configurato per ascoltare 
sull'interfaccia giusta per somaclient, risponder.

Nel caso somad ascolti su una porta diversa da quella 
standard,  necessario specifica a somaclient qual . 
L'opzione per farlo  -P o --port:

somaclient -S localhost -P 12345 <argomenti>

3.3.2 --password

-pw o --password controlla se la password inserita  
corretta oppure no.

somaclient -S localhost -pw

Somaclient chieder la password e risponder in maniera 
affermativa o no.

3.3.3 --readdirectory e --readpalinsesto

Con le opzioni -rd o --readdirectory somaclient 
comunica a somad di rileggersi le directory che sono 
state specificate nel palinsesto. Con -rp o 
--readpalinsesto, somad si rilegger il palinsesto. 
Queste sono utili nel caso si sia modificato il 
palinsesto o si siano aggiunti o rimossi file dentro le 
directory che somad utilizza come playlist.:

somaclient -S localhost -rd

3.3.4 --filepalinsesto

Se si vuole cambiare palinsesto a somad, si utilizza 
questa optione. Il file che deve essere presente sul 
computer su cui si lancia somaclient verr inviato a 
somad, vagliato e se corretto, sostituito al palinsesto 
utilizzato.

somaclient -S localhost -fp nuovo_palinsesto.cfg

3.3.5 --oldpalinsesto

Imposta come palinsesto di somad quello specificato nel 
file soma.cfg. Serve per ripristinare la situazione iniziale:

somaclient -S localhost -op

3.3.6 --getpalinsesto

Scrive a schermo, in una versione schematizzata, il 
palinsesto utilizzato da somad.

somaclient -S localhost -gp

3.3.7 --nextsong

Con -ns o --nextsong somaclient impone a somad di 
eseguire un pezzo specifico senza tener conto del palinsesto:

somaclient -S localhost -ns Battisti.ogg

3.3.8 --status

Mostra che cosa sta facendo in questo preciso istante 
somad. Pu quindi mostrare il brano che somad sta 
gestendo, oppure fino a quando somad sar in pausa, o 
semplicemente se  andato a buon fine il comando che si 
 dato.

somaclient -S localhost -st

3.3.9 --running

Ritorna se somad  stoppato o se sta girando.

somaclient -S localhost -r

3.3.10 --quit

Chiude somad definitivamente. Bisogna poi rilanciarlo a 
mano. E' una operazione che non ha alcun senso se si 
vuole stoppare momentaneamente somad. Esiste una 
optione apposita.

somaclient -S localhost -q

3.3.11 --stop e --start

--stop stoppa somad fino a che non lo si restarta 
(--start). Si pu anche passare un argomento a --stop 
per indicare fra quanti secondi somad deve ripartire.

La sintassi :

somaclient -S localhost --stop

Se si vuole specificare un tempo dopo il quale soma 
deve ripartire, si pu usare una sintassi molto varia: 
si pu impostare minuti, secondi, ora cosi': 1H20m4s 
attraverso le lettere h o H (ore), m o M (minuti), e s 
o S (secondi). Se non si mette niente viene 
interpretato il numero come secondi.

somaclient -S localhost --stop 45M23

3.3.12 --code

Se bisogna utilizzare somaclient da un'altro programma 
e' comodo un output numerico. Con -c somaclient ritorna 
qualsiasi output dei comandi spiegati sopra in formato 
numerico. Ecco i codici:

* 0 - Errore generico.

* 1 - Errore nei parametri

* 2 - Specificare il server

* 3 - Errore creazione socket.

* 4 - Errore nel risolvere l'host.

* 5 - Errore nella connessione.

* 6 - Errore di protocollo.

* 7 - Password errata!

* 8 - Errore apertura file di palinsesto.

* 9 - Done.

* 10 - Errore interno.

* 11 - Errore di locking della struttura dati.

* 12 - Si'. Somad sta girando.

* 13 - No. Somad e' stoppato.

3.3.13 -pPASSWORD

Quando somaclient si collega ad un server, chiede la 
password. Se si vuole saltare questo passaggio, e' 
possibile scrivere la password a riga di comando 
attraverso -p<password>.

Esempio:

somaclient -S localhost -pPROVA_PASS

3.3.14 Shell mode

La seconda modalit di avvio di somaclient  quella di 
shell. Mentre se si specificano le opzioni, somaclient 
si collega a somad, effettua l'operazione richiesta e 
si chiude, se non si mettono argomenti oltre a 
--server, --port ed eventualmente --p<PASSWORD>, 
somaclient compare come shell a tutti gli effetti.

I comandi che conosce sono:

exit - uscita dalla shell

quit - uscita dalla shell

help - menu di aiuto

? - come help

cd - cambia directory

pwd - scrive in che directory ci si trova

ls - comando ls :)

list - come ls

send - invia un messaggio a somad. Questi possono 
essere: readdirectory, readpalinsesto, oldpalinsesto, 
password, status, quit, filepalinsesto, stop, start, 
running, nextsong. Tutti gi spiegati sopra.

3.4 Altri software

Esistono altri software che si possono associare alla 
suite Soma. Oltre ai moduli di cui si parler pi 
avanti, esistono due interfaccie grafice a somaclient. 
Una via web chiamata SomAdmin e una grafica in gtk2 
chiamata SomaX.

Non spiegher nel dettaglio nessuna delle due, ma via 
accenno che graziea SomAdmin  possibile amministrare 
la propria radio via web attraverso un calendario 
online accessibile con 3 modalit di accesso:

* autorizzazione per l'inserimento e la modifica

* accesso anonimo per l'inserimento e autorizzato per 
  la modifica (radio openpublishing)

* accesso anonimo in ogni aspetto.

SomaX  un applicativo grafico per semplificare la vita 
a chi sta poi effettivamente in radio. Permette di fare 
4 cose sole rispetto a quello che fa somaclient: 
rileggere il palinsesto, rileggere le directory, 
stoppare e far ripartire. Sono le 4 operazioni che un 
DJ deve sapere fare per dirigere bene la sua 
trasmissione e grazie a questo software fatto a 
pulsanti, ognuno pu lavorare senza sapere troppo di 
come si configura, gestisce, amministra una suite come Somad.

Tutti questi applicativi sono scaricabili dal solito 
sito: http://soma.realityhacking.org.

4 Struttura di una radio

Adesso che  stato chiarito l'utilizzo dei software 
della suite Soma, passo a spiegare come poi in una 
situazione reale, questo marchingegno oscuro pu essere 
utilizzato in una radio.

Una radio tendenzialmente divide la giornata in 
trasmissioni ove, oltre al parlato del dj c' musica da 
parte o spot. Non serve quindi solo soma per fare una 
radio a meno che non si scelga di fare una radio che 
produce solo musica. La parte di gestione delle 
trasmissioni la si fa con la siute soma, il dj parla, 
magari si sommano altre sorgenti sonore come dirette, 
interviste, pi dj e poi il tutto va inviato 
all'antenna o al server di streaming. Ho fatto questo 
schema appositamente per spiegare come il tutto sia possibile:

<Graphics file: doc/radio.jpg>


Questo schema  orientato ad una radio via web, ma  
facilmente esportabile ad una radio in etere. Qui parlo 
anche di un altro elemento non presente nella suite 
soma chiamato somaplayer. Potete trovare lui e la 
documentazione legata sul sito 
http://soma.realityhacking.org. 

Sono 3 esempi di possibili radio:

4.1 Primo esempio

Una radio che produce solo musica, ha bisogno di un 
buon repository di file audio (locale o remoto) e poi 
un sistema di diffusione. Per fare questo serve solo la 
suite Soma configurata in maniera abbastanza standard.

Si pensa al palinsesto, lo si configura a dovere, poi 
lo si lancia e non c' bisogno di manutenzione 
particolare se non quandi si vuole cambiare la scaletta 
o le playlist.

4.2 Secondo esempio

Il secondo esempio presente nel grafico mostra una 
radio che miscela due impulsi: uno preso da un 
repository dove somad schedula musica, il secondo 
derivante da uno o pi microfoni. Per fare questo serve 
un miscelatore di impulsi sonori. Il miscelatore pu 
essere la scheda sonora se  full-duplex abbianata poi 
ad un mixer o a un software che gestisce la sorgente in 
uscita in qualche modo (streammandola ad esempio). Ne 
esistono tantissimi, ma non mi sembra di portare acqua 
al mio mulino se suggerisco SdS (guardare somaplayer). 
Lo suggerisco perch a differenza di un demone del 
suono normale  capace di processare le sorgenti sonore 
e di sommarle in una e di questa gestirla in sfariate 
forme di output senza l'utilizzo di altri programmi aggiuntivi.

4.3 Terzo esempio

Il terzo esempio  il pi complesso. Ipotizzo una rete 
(anche internet) atta a produrre una sorgente sonora 
unificata. Qui  il trionfo di SdS. Somad riveste il 
ruolo di scheduler dei palinsesti, il software che da i 
tempi alla radio.

<Graphics file: doc/soma.jpg>


L'idea complessiva di questa rete impotetica  
riassunta in questo schema. Notate che l'output di 
generato da somad  uno dei tanti gestito a sinistra da 
SdS e da destra da darkice. La differenza tra darkice e 
SdS  che darkice non somma sorgenti sonore che 
arrivano dalla rete, al contrario di SdS nato 
appositamente per questo.

L'idea di questa immagine  quella di mostrare come 
l'output poi viene messo in condivisione comunque 
attraverso un server di streaming come icecast.

5 Moduli

Somad supporta moduli. Possono essere caricati runtime 
senza bisogno di ricompilazioni, stop, riavvi e cose di 
questo tipo. In questo capito spiegher in una prima 
parte come somad vede e comunica con i moduli e in una 
seconda sezione come scrivere moduli.

I moduli sono delle librerie scritte separatamente 
dalla suite soma e che ognuno pu produrre in base alle 
sue esigenze aggiungendo funzionalit aggiuntive. Io ho 
scritto un modulo solo chiamato somadiff.so che 
permette di mandare in differita una trasmissione 
mandata via web da una radio.

Non  questa la sede per parlare di somadiff, 
reperibile anch'esso dal sito internet per progetto 
soma, ma  utile capire come creare un palinsesto in 
modo che somad utilizzi il modulo:

Palinsesto {

  Description = "trasmissione tipo"

  Type = module

  Module = somadiff.so

  Start=1000

  Stop =2110

}

Questo  tutto quello che serve scrivere.

Quando saranno le 1000 somad sceglier questo 
palinsesto, caricher il modulo somadiff.so e dar il 
controllo a questa libreria. Per tutto il tempo 
monitorer cosa somadiff fa finch alle 2110 concluder 
questo palinsesto e passer al successivo.

Somadiff in particolare non  solo un modulo ma  un 
duplice programma: un server di download, e un modulo 
per somad. Il server scaricher tutte le trasmissioni 
che attraverso uno specifico client si aggiungono al 
database; il modulo render disponibili a somad queste 
registrazioni basandosi sulla descrizione.

Per compilare un modulo, e ancora di pi per scriverlo, 
bisogna guardarsi il file soma.h, file installato 
assieme ai programmi della suite soma.

5.1 Programmazione di moduli

L'header soma.h descrive 5 funzioni che un modulo deve 
contenere per essere compatibile con somad. Queste 
funzioni sono:

char * module_run(soma_pl *, int);

deve ritornare qualcosa di buono per un player. Sar 
poi soma a selezionare il player opportuno.

int module_web(soma_pl *, int);

Deve ritornare se quello che torner sar un file o uno 
streaming.

int module_quit(soma_pl *);

Chiusura del modulo

char *module_name(void);

Deve ritornare il nome del modulo

int module_time_stop(somapl *, int);

Deve ritornare un numero che  la durata massima della 
sorgente sonora.

L'argomento soma_pl * passato e' una struttura che 
ricalca a pieno la codifica del palinsesto che ha 
richiamto il modulo, mentre int  il tempo espresso con 
la sintassi solita.

5.1.1 soma_pl

typedef struct _soma_pl_ {

  char *Description;

  int Start;

  int Stop;

  int Type;

  int Random;

  int SoftStop;

  int RatioSong;

  int RatioSpot;

  soma_dir *PathSong;

  soma_dir *PathSpot;

  char *Stream;

  char *Jingle;

  char *Module;

  struct _soma_pl_ *next;

  struct _soma_pl_ *prev;

} soma_pl; 

Questa struttura descrive un palinsesto. Attraverso i 
dati di questa il modulo pu capire perch  stato 
lanciato e cosa deve fare.

Il modulo somadiff in particolare analizza il campo 
description e fa una ricerca nel database gestito dal 
server somadiff.

5.2 Esempio

Un esempio semplice potrebbe essere questo:

#include <soma/soma.h>

/* Cosa deve lanciare somad ? Sempre battisti... */

char *module_run(soma_pl *pl, int a) {

  return "/mp3/battisti.ogg";

}

/* Sar un file o uno streaming ? Utilizzo le dfine 
PLAY_FILES o PLAY_STREAM */

int module_web(soma_pl *pl, int a) {

  return PLAY_FILES;

}

/* Funzione di chiusura */

int module_quit(soma_pl *pl) {

  return 0;

}

/* nome del modulo */

char *module_name(void) {

  return "modulo_esempio";

}

/* Dopo quanto deve fermarsi? Se 0 vuol dire quando 
finisce il player. Se invece indico un numero, vuol 
dire che dopo X secondo se il player non ha finito, 
verr stoppato */

int modul_time_stop(soma_pl *pl, int a) {

  return 0;

}

Questo semplice modulo, descrive tutte le funzioni di 
cui somad ha bisogno.

6 Conclusione

Non  stato semplice spiegare tutto... e penso pure di 
essermi dimenticato qualcosa. Sviluppare un software 
opensource vuol dire prima di tutto instaurare una 
buona relazione tra programmatori e utenti. Scrivetemi 
quindi per consigli, problemi o idee.

bakunin
