SAM Broadcaster : créer et utiliser des scripts PAL

PAL, pour Playlist Automation Language, permet d’automatiser SAM Broadcaster : rotation musicale, jingles, horaires, encodeurs, métadonnées et émissions distantes. Ce guide explique comment créer, tester et organiser vos premiers scripts PAL sans bloquer la diffusion.

SAM Broadcaster sait déjà enchaîner des titres, gérer plusieurs lecteurs et envoyer un flux vers un serveur de diffusion. Les scripts PAL permettent d’aller beaucoup plus loin en définissant précisément la logique de votre radio.

Vous pouvez, par exemple, programmer un jingle toutes les cinq chansons, imposer une catégorie à une heure donnée, démarrer les encodeurs automatiquement ou modifier les informations affichées dans le flux.

PAL reste propre à SAM Broadcaster. Sa syntaxe rappelle Pascal, tandis que ses classes donnent accès aux catégories, à la file d’attente, aux lecteurs, aux encodeurs et aux informations des morceaux.

Qu’est-ce qu’un script PAL ?

PAL signifie Playlist Automation Language. Il s’agit du langage de script intégré à SAM Broadcaster Pro.

Un script PAL peut intervenir sur presque toutes les étapes de l’automatisation :

• choisir un titre dans une catégorie ;
• ajouter un morceau en haut ou en bas de la file d’attente ;
• respecter ou ignorer les règles de rotation ;
• attendre un nombre déterminé de chansons ;
• attendre une heure ou un intervalle précis ;
• lancer ou arrêter les encodeurs ;
• agir sur les lecteurs ;
• modifier les métadonnées envoyées aux auditeurs ;
• charger une playlist externe ;
• connecter une émission distante ;
• écrire des informations dans le journal de SAM.

PAL convient particulièrement aux tâches répétitives. Dès qu’une action doit suivre une règle prévisible, un script peut souvent éviter une intervention manuelle.

SAM Broadcaster Pro ou SAM Broadcaster Cloud ?

Ce guide concerne principalement SAM Broadcaster Pro, l’application Windows dans laquelle l’environnement PAL est directement intégré.

SAM Broadcaster Cloud propose sa propre logique d’automatisation avec des règles de rotation, des tâches et des blocs de programmation. Ne supposez donc pas qu’un script PAL conçu pour SAM Broadcaster Pro peut être copié tel quel dans l’offre Cloud.

Créer son premier script PAL

La création d’un script s’effectue depuis la fenêtre PAL de SAM Broadcaster.

1. Dans SAM Broadcaster, ouvrez Menu → Window → PAL Scripts.
2. Cliquez sur le bouton + pour ajouter un script.
3. Choisissez l’emplacement du fichier portant l’extension .pal.
4. Activez la création du fichier lorsqu’il n’existe pas encore.
5. Validez l’ajout du script.
6. Sélectionnez-le, puis ouvrez-le dans l’éditeur PAL intégré.

La fenêtre PAL permet ensuite de démarrer, suspendre ou arrêter chaque script. Elle indique également son état et peut le lancer automatiquement au démarrage de SAM.

Choisir un dossier dédié aux scripts

Évitez de disperser les fichiers PAL dans plusieurs répertoires. Créez un dossier dédié, par exemple :

C:\SAM\PAL\

Vous pourrez ensuite organiser les fichiers selon leur fonction :

C:\SAM\PAL\rotation\
C:\SAM\PAL\jingles\
C:\SAM\PAL\horaires\
C:\SAM\PAL\encodeurs\
C:\SAM\PAL\tests\

Cette organisation facilite les sauvegardes et limite les modifications accidentelles d’un script utilisé en production.

Découvrir l’éditeur PAL intégré

L’éditeur PAL intégré à SAM Broadcaster ne se limite pas à une simple zone de texte. Il permet de compiler le script, repérer les erreurs, afficher leur ligne et suivre la sortie produite par les commandes de journalisation.

Le workflow recommandé reste simple :

1. modifiez le script ;
2. enregistrez le fichier ;
3. compilez-le ;
4. corrigez toutes les erreurs signalées ;
5. exécutez-le sur une copie ou une programmation de test ;
6. contrôlez la file d’attente et le journal ;
7. activez son démarrage automatique uniquement après validation.

L’éditeur permet également une exécution pas à pas. Cette fonction devient utile lorsqu’un script comporte plusieurs conditions ou manipule plusieurs objets.

Premier exemple : écrire dans la sortie PAL

Commencez par un script sans effet sur la diffusion. Il permet de vérifier que l’environnement fonctionne correctement.

WriteLn('Bonjour depuis mon premier script PAL');Langage du code : JavaScript (javascript)

Compilez puis exécutez le script. Le message doit apparaître dans le panneau de sortie de l’éditeur.

Sur les versions de SAM Broadcaster prenant en charge PAL.Log(), vous pouvez aussi écrire dans le journal des événements :

PAL.Log('Le script PAL a démarré', ltNotice);Langage du code : JavaScript (javascript)

Les niveaux disponibles permettent notamment de distinguer une information normale d’un avertissement. Cette journalisation facilite le diagnostic lorsqu’un script fonctionne en arrière-plan.

Comprendre la structure d’un script PAL

PAL utilise une syntaxe proche de Pascal. Les instructions se terminent généralement par un point-virgule.

Les commentaires

Documentez les réglages modifiables, les catégories utilisées et le but du script.

// Commentaire sur une ligne.

{ Commentaire
  sur plusieurs lignes. }Langage du code : JavaScript (javascript)

Les variables

Les variables doivent être déclarées avant leur utilisation :

var
  CategoryName : String;
  TrackCount   : Integer;
  IsEnabled    : Boolean;

CategoryName := 'Music (All)';
TrackCount   := 5;
IsEnabled    := True;Langage du code : JavaScript (javascript)

Choisissez des noms explicites. Un script diffusé pendant plusieurs années devient vite incompréhensible lorsqu’il contient uniquement des variables nommées a, b et x.

Les blocs begin et end

Lorsque plusieurs instructions dépendent de la même condition, regroupez-les dans un bloc :

if IsEnabled then
begin
  WriteLn('Automatisation activée');
  PAL.Log('Automatisation activée', ltNotice);
end;Langage du code : JavaScript (javascript)

Les commandes d’attente : la base d’un bon script PAL

Un script PAL ne doit pas vérifier une condition en permanence dans une boucle rapide. Utilisez les commandes d’attente prévues par SAM.

Les trois commandes fondamentales sont :

PAL.WaitForPlayCount(Count);
PAL.WaitForQueue(Count);
PAL.WaitForTime(Time);Langage du code : CSS (css)

Attendre plusieurs morceaux

PAL.WaitForPlayCount(5);
WriteLn('Cinq morceaux ont commencé leur lecture');Langage du code : JavaScript (javascript)

Le compteur diminue chaque fois qu’un nouveau morceau commence sur un lecteur.

Attendre un état précis de la file

PAL.WaitForQueue(2);
WriteLn('La file contient maintenant deux éléments');Langage du code : JavaScript (javascript)

Cette commande attend que la file contienne exactement le nombre demandé. Elle peut donc rester bloquée si un autre script maintient constamment davantage de titres dans la queue.

Attendre un intervalle

PAL.WaitForTime('+00:00:10');
WriteLn('Dix secondes se sont écoulées');Langage du code : JavaScript (javascript)

Le signe + indique un délai relatif.

Attendre une heure donnée

PAL.WaitForTime('14:30:00');
WriteLn('Il est 14 h 30');Langage du code : JavaScript (javascript)

Vous pouvez utiliser des masques horaires :

PAL.WaitForTime('XX:00:00');
WriteLn('Début de la prochaine heure');Langage du code : JavaScript (javascript)

XX représente ici la prochaine heure correspondante.

Attention aux horaires déjà dépassés

Une attente portant sur une heure fixe du jour peut être immédiatement considérée comme satisfaite lorsque cette heure est déjà passée.

Par exemple, si le script démarre à 17 heures :

PAL.WaitForTime('10:00:00');
WriteLn('Action de 10 heures');Langage du code : JavaScript (javascript)

l’action peut être exécutée immédiatement, puisque 10 heures est antérieur à l’heure actuelle.

Pour une programmation quotidienne plus robuste, prévoyez explicitement le prochain jour lorsque l’horaire est dépassé :

var
  NextRun : DateTime;

NextRun := T['10:00:00'];

if NextRun <= Now then
  NextRun := NextRun + 1;

PAL.WaitForTime(NextRun);
WriteLn('Exécution quotidienne à 10 heures');Langage du code : JavaScript (javascript)

L’ajout de 1 à une valeur DateTime correspond au jour suivant.

Créer une boucle PAL sans monopoliser le processeur

De nombreuses automatisations doivent se répéter. PAL permet de relancer automatiquement le script avec :

PAL.Loop := True;Langage du code : PHP (php)

Placez ensuite une véritable commande d’attente dans le script :

PAL.Loop := True;

PAL.WaitForPlayCount(5);
WriteLn('Action exécutée après cinq morceaux');Langage du code : PHP (php)

À la fin du fichier, SAM relance le script. Celui-ci attend à nouveau cinq morceaux.

Évitez en revanche les boucles sans pause :

// À éviter : boucle active sans attente.
while True do
begin
  WriteLn('Cette boucle ne laisse jamais le script respirer');
end;Langage du code : PHP (php)

Une telle boucle peut gaspiller du processeur, saturer la sortie et rendre SAM moins réactif.

Ajouter un titre aléatoire à la file d’attente

La classe Cat permet d’accéder aux catégories de la bibliothèque musicale.

Cat['Music (All)'].QueueBottom(smRandom, EnforceRules);Langage du code : CSS (css)

Cette ligne choisit aléatoirement un titre dans la catégorie Music (All), applique les règles de rotation, puis l’ajoute en bas de la file.

Pour le placer en tête :

Cat['Jingles'].QueueTop(smRandom, EnforceRules);Langage du code : CSS (css)

Le nom de la catégorie doit correspondre exactement à celui utilisé dans SAM Broadcaster.

Respecter ou ignorer les règles de rotation

EnforceRules demande à SAM de respecter les règles configurées pour la rotation. Selon la commande utilisée, NoRules permet de les ignorer.

N’utilisez NoRules que lorsque la répétition éventuelle du morceau ne pose aucun problème, par exemple pour un signal technique très précis.

Exemple : ajouter un jingle toutes les cinq chansons

PAL.Loop := True;

// Attendre cinq nouveaux morceaux.
PAL.WaitForPlayCount(5);

// Ajouter un jingle en tête de la file.
Cat['Jingles'].QueueTop(smRandom, EnforceRules);

PAL.Log('Un jingle a été ajouté à la file', ltNotice);Langage du code : PHP (php)

Ce script constitue une base simple. Une radio plus complexe devra également tenir compte des autres scripts qui alimentent la file et des éléments déjà programmés.

Le tutoriel SAM Broadcaster : jouer une pub ou un jingle toutes les cinq chansons détaille ce cas d’usage.

Exemple : jouer une promotion toutes les trente minutes

PAL.Loop := True;

// Attendre trente minutes.
PAL.WaitForTime('+00:30:00');

// Ajouter une promotion en tête de la file.
Cat['Promos (All)'].QueueTop(smRandom, EnforceRules);

PAL.Log('Promotion programmée', ltNotice);Langage du code : PHP (php)

Un intervalle relatif de trente minutes signifie que le délai repart après chaque exécution. Il ne garantit pas une diffusion exactement à la minute 00 ou 30 de chaque heure.

Pour viser la demi-heure suivante, utilisez plutôt un masque horaire adapté :

PAL.Loop := True;

PAL.WaitForTime('XX:30:00');
Cat['Promos (All)'].QueueTop(smRandom, EnforceRules);Langage du code : PHP (php)

Exemple : démarrer automatiquement les encodeurs

PAL peut parcourir les encodeurs configurés dans SAM et démarrer ceux qui sont arrêtés.

var
  I : Integer;

// Laisser SAM et sa base terminer leur démarrage.
PAL.WaitForTime('+00:00:10');

for I := 0 to Encoders.Count - 1 do
begin
  if not Encoders[I].Started then
  begin
    Encoders[I].Start;
    PAL.Log(
      'Encodeur démarré : ' + IntToStr(I),
      ltNotice
    );
  end;
end;Langage du code : JavaScript (javascript)

Le délai initial évite de solliciter les encodeurs avant que SAM, la base de données et la connexion réseau soient prêts.

Ce script doit être exécuté une seule fois au démarrage. N’activez pas PAL.Loop sans nécessité.

Exemple : démarrer les encodeurs et lancer un morceau

var
  I            : Integer;
  CategoryName : String;
  Player       : TPlayer;
  Song         : TSongInfo;

CategoryName := 'Music (All)';

// Attendre que SAM soit complètement disponible.
PAL.WaitForTime('+00:00:10');

// Démarrer les encodeurs arrêtés.
for I := 0 to Encoders.Count - 1 do
begin
  if not Encoders[I].Started then
    Encoders[I].Start;
end;

// Choisir un titre.
Song := Cat[CategoryName].ChooseSong(
  smRandom,
  EnforceRules
);

// Utiliser le lecteur disponible.
Player := IdlePlayer;
Player.QueueSong(Song);
Player.Play;

PAL.Log(
  'Lecture démarrée : ' +
  Song['artist'] + ' - ' +
  Song['title'],
  ltNotice
);

// Libérer les objets.
Player.Free;
Song.Free;Langage du code : JavaScript (javascript)

Testez ce script lorsque SAM est arrêté ou inactif. Il n’est pas conçu pour prendre le contrôle d’une diffusion déjà en cours.

Créer une rotation musicale variée

Une rotation cohérente ne consiste pas à sélectionner continuellement un titre au hasard dans toute la bibliothèque. Elle doit répartir les catégories et éviter les répétitions trop rapprochées.

Une logique simple peut alterner plusieurs catégories :

PAL.Loop := True;

Cat['Hits'].QueueBottom(smRandom, EnforceRules);
Cat['Gold'].QueueBottom(smRandom, EnforceRules);
Cat['Découvertes'].QueueBottom(smRandom, EnforceRules);
Cat['Gold'].QueueBottom(smRandom, EnforceRules);

PAL.WaitForQueue(2);Langage du code : PHP (php)

Le script recharge la file lorsqu’elle revient à deux éléments. Vérifiez toutefois qu’aucun autre script n’attend le même seuil ou ne maintient la queue à une autre longueur.

Consultez également le guide Script PAL pour SAM Broadcaster : créer une playlist variée par rotation automatique.

Programmer un style musical sur un créneau horaire

PAL peut modifier la rotation selon l’heure. Vous pouvez ainsi réserver une catégorie à une tranche nocturne, une émission spécialisée ou un rendez-vous hebdomadaire.

La logique générale consiste à :

1. attendre le début du créneau ;
2. vider ou compléter prudemment la file ;
3. ajouter des morceaux de la catégorie souhaitée ;
4. attendre la fin du créneau ;
5. restaurer la rotation normale.

Le tutoriel Script PAL pour SAM Broadcaster : jouer un style de musique pendant un créneau horaire fournit un exemple spécialisé.

Programmer un signal horaire

Un signal horaire doit être placé suffisamment tôt dans la file pour approcher l’heure cible. La durée du morceau déjà en cours peut empêcher une synchronisation à la seconde près.

PAL.Loop := True;

PAL.WaitForTime('XX:00:00');
Cat['Time Signal'].QueueTop(smRandom, NoRules);Langage du code : PHP (php)

Ce script ajoute le signal lorsque l’heure est déjà atteinte. Il ne peut donc pas interrompre proprement un titre en cours pour garantir une précision absolue.

Pour une programmation plus précise, tenez compte de la durée des éléments présents dans la file et utilisez les fonctions prévues pour les événements fixes.

Le guide SAM Broadcaster : jouer un bip horaire avec un script PAL traite ce cas en détail.

Modifier les informations affichées dans le flux

Les métadonnées envoyées au serveur de streaming permettent d’afficher le titre, l’artiste ou un message personnalisé dans le lecteur des auditeurs.

Cette fonction peut servir à :

• annoncer le nom d’une émission ;
• faire défiler une information ;
• masquer temporairement le titre réel ;
• afficher une URL ou un message de la station ;
• adapter les données pendant une émission distante.

Consultez le tutoriel Script PAL pour SAM Broadcaster : changer ou faire défiler les informations du flux audio.

Importer une playlist externe

SAM Broadcaster inclut traditionnellement un exemple PAL capable de charger une playlist M3U dont le nom dépend de la date.

var
  FileName : String;

FileName := FormatDateTime('yymmdd', Now) + '.m3u';

WriteLn('Chargement de : ' + FileName);

Queue.Clear;
Queue.AddList(
  'C:\Playlists\' + FileName,
  ipBottom
);

PAL.Loop := True;
PAL.WaitForTime('23:59:59');Langage du code : PHP (php)

Ce script suppose qu’un fichier correspondant à chaque date existe dans le dossier indiqué.

Queue.Clear efface toute la file. Utilisez cette commande avec prudence, surtout lorsque d’autres scripts ou animateurs ajoutent déjà des contenus.

Travailler avec des fichiers situés sur un autre disque

SAM Broadcaster peut utiliser des fichiers placés sur un autre disque local. Il suffit d’indiquer leur chemin complet lorsque la commande PAL attend un fichier ou une playlist.

Queue.AddList(
  'D:\Radio\Playlists\programme.m3u',
  ipBottom
);Langage du code : JavaScript (javascript)

Pour un chemin réseau, utilisez un emplacement accessible au compte Windows qui exécute SAM. Un lecteur réseau visible dans votre session interactive peut ne pas être disponible après un démarrage automatique.

Préférez alors un chemin UNC :

\\serveur-audio\radio\playlists\programme.m3uLangage du code : CSS (css)

Vérifiez les droits de lecture, la disponibilité du partage et le comportement du script lorsque le serveur distant ne répond pas.

Éviter les conflits entre plusieurs scripts PAL

Plusieurs scripts peuvent fonctionner simultanément, mais ils partagent les mêmes lecteurs, encodeurs et files d’attente.

Les conflits les plus fréquents apparaissent lorsque :

• deux scripts remplissent la queue au même moment ;
• un script vide la file préparée par un autre ;
• plusieurs scripts utilisent le même seuil avec WaitForQueue() ;
• deux scripts imposent des catégories différentes ;
• un script démarre un encodeur que l’animateur souhaite garder arrêté ;
• plusieurs scripts modifient les mêmes métadonnées ;
• un événement horaire entre en concurrence avec une émission distante.

Attribuez une responsabilité claire à chaque fichier. Un script doit, autant que possible, gérer une seule fonction.

Rendre ses scripts PAL plus fiables

Centraliser les réglages

Placez les noms de catégories et les intervalles au début du fichier :

var
  JingleCategory : String;
  SongsBetween   : Integer;

JingleCategory := 'Jingles';
SongsBetween   := 5;Langage du code : JavaScript (javascript)

Vous éviterez ainsi de modifier la même valeur à plusieurs endroits.

Journaliser les actions importantes

PAL.Log(
  'Ajout d’un élément depuis la catégorie Jingles',
  ltNotice
);Langage du code : JavaScript (javascript)

Un script silencieux paraît souvent fiable jusqu’au jour où il cesse de fonctionner à trois heures du matin.

Ne pas ignorer toutes les règles

Les règles de rotation évitent notamment les répétitions rapprochées d’un artiste, d’un album ou d’un morceau. Utilisez EnforceRules par défaut.

Prévoir les catégories vides

Une catégorie vide ou renommée peut interrompre la logique du script. Contrôlez régulièrement les catégories utilisées et ne modifiez pas leur nom sans mettre à jour les fichiers PAL associés.

Tester les redémarrages

Un script peut fonctionner parfaitement lorsqu’il démarre le matin, puis exécuter immédiatement plusieurs actions lorsqu’il est relancé l’après-midi. Testez donc différents horaires de démarrage.

Sauvegarder les scripts séparément

Conservez une copie versionnée des fichiers PAL. Git convient très bien, même si SAM Broadcaster lui-même n’utilise pas ce système.

N’enregistrez pas dans le dépôt public des mots de passe, URL privées ou informations d’accès aux serveurs de diffusion.

Déboguer un script PAL

Lorsqu’un script ne produit pas le résultat attendu, commencez par distinguer une erreur de compilation d’une erreur logique.

Erreur de compilation

L’éditeur indique généralement la ligne, la colonne et la nature du problème. Vérifiez en priorité :

• les points-virgules manquants ;
• les parenthèses non refermées ;
• les blocs begin sans end ;
• les guillemets absents ;
• les variables non déclarées ;
• les noms de fonctions incorrects.

Erreur logique

Le script compile, mais son comportement reste incorrect. Ajoutez alors des messages avant et après chaque étape :

WriteLn('Avant l’attente');
PAL.WaitForPlayCount(5);
WriteLn('Après l’attente');

PAL.Log(
  'La commande WaitForPlayCount est terminée',
  ltNotice
);Langage du code : JavaScript (javascript)

Cette méthode permet de repérer l’instruction sur laquelle le script reste bloqué.

Le script reste en attente

Une commande d’attente peut fonctionner exactement comme prévu tout en donnant l’impression d’un blocage.

• WaitForPlayCount() attend de nouveaux démarrages de morceaux.
• WaitForQueue() attend une taille exacte de la file.
• WaitForTime() attend l’heure ou la date calculée.

Affichez la condition attendue dans le journal et observez la file d’attente avant de conclure à une panne.

Checklist avant d’activer un script sur la radio

Aller plus loin avec SAM Broadcaster et Icecast

Les scripts PAL pilotent la programmation dans SAM Broadcaster. Ces guides permettent d’approfondir chaque automatisation et de compléter la chaîne de diffusion.

• Jouer une publicité ou un jingle toutes les cinq chansons
• Créer une playlist variée par rotation automatique
• Jouer un bip horaire avec un script PAL
• Jouer un style musical pendant un créneau horaire
• Changer ou faire défiler les informations du flux audio
• Créer une webradio avec SAM Broadcaster et Icecast
• Scrobbler les titres d’un flux Icecast sur Last.fm
• Servir un flux Icecast en HTTPS avec Cloudflare et Nginx

Questions fréquentes

Que signifie PAL dans SAM Broadcaster ?

PAL signifie Playlist Automation Language. Ce langage intégré à SAM Broadcaster permet d’automatiser les playlists, catégories, horaires, encodeurs, lecteurs et métadonnées.

Où créer un script PAL ?

Ouvrez Menu → Window → PAL Scripts, puis cliquez sur le bouton d’ajout. Choisissez ou créez un fichier portant l’extension .pal, puis ouvrez-le dans l’éditeur intégré.

Comment lancer automatiquement un script PAL ?

Ouvrez la configuration du script dans la fenêtre PAL, puis activez l’option de démarrage automatique. Testez d’abord son comportement lorsque SAM est lancé à différents moments de la journée.

Comment jouer un jingle toutes les cinq chansons ?

Utilisez PAL.WaitForPlayCount(5), puis ajoutez un titre de la catégorie des jingles avec QueueTop() ou QueueBottom(). Activez ensuite PAL.Loop pour répéter l’opération.

Pourquoi mon script PAL reste-t-il bloqué ?

Il attend probablement une condition qui n’est jamais atteinte. Vérifiez notamment la valeur passée à WaitForQueue(), les horaires, les noms des catégories et les actions des autres scripts.

Peut-on utiliser plusieurs scripts PAL en même temps ?

Oui, mais ils partagent les lecteurs, la file, les catégories et les encodeurs. Évitez que plusieurs scripts manipulent simultanément la même ressource sans coordination.

PAL fonctionne-t-il avec SAM Broadcaster Cloud ?

Les scripts présentés ici ciblent SAM Broadcaster Pro. SAM Broadcaster Cloud possède ses propres outils de rotation, tâches et programmation. Les deux environnements ne doivent pas être confondus.

Conclusion

PAL transforme SAM Broadcaster en véritable moteur d’automatisation radiophonique. Une courte instruction peut ajouter un jingle, attendre un horaire, charger une playlist ou démarrer les encodeurs.

Commencez par un script simple. Compilez-le, journalisez ses actions et observez son effet sur la file. Ajoutez ensuite les conditions, horaires et rotations progressivement.

La principale difficulté ne vient pas de la syntaxe. Elle vient des interactions entre les scripts, les règles de rotation et la programmation existante.

Un bon script PAL doit donc faire trois choses : attendre intelligemment, agir précisément et laisser suffisamment de traces pour expliquer ce qu’il a fait.

Sources et documentation

• Spacial : documentation des scripts PAL
• Spacial : environnement de développement PAL
• Spacial : guide de démarrage rapide PAL
• Spacial : premier script PAL
• Spacial : démarrer automatiquement SAM Broadcaster avec PAL
• Spacial : commandes PAL ajoutées aux versions récentes
• Spacial : SAM Broadcaster Pro

Report a typo