IcecastStreaming Handbook

IcecastEzstreamIcesVideoLanClient

CreatedBy DavidChilders

www.scvi.net

License IcecastStreamingHandbookreleasedundertheGNUGeneralPublicLicense Version2,June1991 http://www.gnu.org/licenses/oldlicenses/gpl2.0.html IcecastStreamingHandbookresearchedandcreatedbyDavidChilders IcecastdocumentationwrittenbymembersoftheXiphfoundationcommunity. EzstreamdocumentationwrittenbymembersoftheXiphfoundationcommunity. EzstreamManPagewrittenbyMoritzGrimm. IceS2.0documentationwrittenbymembersoftheXiphfoundationcommunity. IceS0.4documentationwasmostlywrittenbyAlexanderHavng. VideoLanClientdocumentationwrittenbymembersoftheVideoLanClientcommunity. Oldstylemicrophoneimageretrievedfrom:http://www.clker.com/clipart26834.html

Index

Icecast Changes Introduction BasicSetup ConfigFile AdminInterface ServerStatistics Relaying ListingInAYPDirectory ListenerAuthentication Win32SpecificDocumentation Glossary FrequentlyAskedQuestions Usage Installation Prerequisites AboutEzstream

Ezstream

ExternalDecoders/Encoders OperatingSystemSpecificNotes InformationAboutTheBinaryEzstreamDistribution ForWindows EzstreamMetadataExampleXMLConfigurationFile EzstreamMp3ExampleXMLConfigurationFile EzstreamReencodeMp3ExampleXML ConfigurationFile EzstreamVorbisExampleXMLConfigurationFile EzstreamReencodeVorbisExampleXML ConfigurationFile EzstreamReencodeTheoraExampleXML ConfigurationFile EzstreamManPage

IceSv2.0 Introduction BasicSetup ConfigFile AvailableInputModules FrequentlyAskedQuestions Introduction What'sItFor? WhatCanItDo? Configuring Licensing DevelopersResources

IceSv0.4

SourcingMultimediaWithTheVideoLanClient(VLC) Introduction InstallingVLCWithlibshoutSupport CommandLineSyntaxForStreamingContentToAn IcecastServer VLCIcecastOutput(CommandLineOptions)

Foreword IhavecreatedacomprehensivereferenceforusersoftheIcecastmultimediastreamingserversoftware.Icecastis averyrobustOpenSourcesoftwareapplicationthatcanbeusedonvariousoperatingsystemsandcanbeusedto streambothaudioandvideomultimedia. IwouldliketothanktheXiphCorporationforcreatingthewonderfulIcecastmultimediaserversoftware,Scarlet CokerforprovidingassistancewiththereviewofthemanuscriptandtoJamesDaveyatBroadcastingWorldfor allowingmetheopportunitytocreatethishandbook. Itismysincerehopethatthereaderfindsthisguideavaluableresource. DavidChilders www.scvi.net July,2009 SustainingMember

SocietyMotionPicture andTelevisionEngineers

OsorrisodeDeusestarasemprecontigo Voceestarasempreemnossoscoracoes Giveapersonafishandyoufeedthemforaday; teachthatpersontousetheInternetandtheywon'tbotheryouforweeks. AuthorUnknown

Icecast2.3.2 Changes Introduction BasicSetup ConfigFile AdminInterface ServerStatistics Relaying ListingInAYPDirectory ListenerAuthentication Win32SpecificDocumentation Glossary FrequentlyAskedQuestions

Changes Version2.3 NewFeatures #Streamingsupportforoggspeex,oggflac,oggmidi #introfilesupportpermountsettable #ondemandrelays,globalandperrelaysettable #fallbacktofile,extendsontheintrofilehandling. #newmountlevelsettings 1.public,type/subtype,genresettings,streamdescription, 2.streamurl,streamname,bitrate(overridewhatissentfromthesourceclient) 3.mp3metadatainterval 4. on[dis]connect scripts can be stated permount, invoked at source start/stop and take 1 arg which is the mountpoint. #NewURLlistenerauthenticator.includedisanexamplephpbasedapplicationthatcanbeusedinconjunction withtheurlauthenticatortomanageasimplesubscriptionbasedbroadcast. #HTPasswdauthenticatorusesinmemorystructuresnow. #Ondemandfilesnowcanbefedthroughanauthenticator #Updatetoadmin/webxsltinterface Fixes #real/helixworks #win32accesslogcorrect #statsclientisstablenow(curlXSTATShttp://admin@host:port/) #showmountpointsonstatsthatareinactivebuthaveanactivefallback #moreupdatesoverHUPpossible

Introduction WhatIsIcecast? IcecastisastreamingmediaserverwhichcurrentlysupportsOggVorbisandMP3audiostreams.Itcanbeusedto createanInternetradiostationoraprivatelyrunningjukeboxandmanythingsinbetween.Itisveryversatilein thatnewformatscanbeaddedrelativelyeasilyandsupportsopenstandardsforcommunicationandinteraction. Therearetwomajorpartstomoststreamingmediaservers:thecomponentprovidingthecontent(whatwecall sourceclients)andthecomponentwhichisresponsibleforservingthatcontenttolisteners(thisisthefunctionof icecast). WhatPlatformsAreSupported? CurrentlythefollowingUnixplatformsaresupported: Linux(MostflavorsincludingRedhatandDebian) FreeBSD OpenBSD Solaris CurrentlythefollowingWindowsplatformsaresupported: WindowsNT Windows2000 WindowsXP WhereDoIGoForQuestions? Therearemanywaystocontacttheicecastdevelopmentteam BestWays Icecastmailinglisthttp://www.xiph.org/archives IcecastDevelopersmailinglisthttp://www.xiph.org/archives IcecastIRCchatroomirc.freenode.net:#icecast AlternateWays team@icecast.org

BasicSetup BasicRequirements ThissectionwilldescribetheessentialrequirementsinsettingupasimpleInternetradiostation.Itisbynomeans acompletelistbutshouldgiveyouenoughtogetstarted. Therearetwomajorcomponentsinvolved:thestreamingserver(icecastinthiscase)andthesourceclient.The icecastserverwillbetheplacewherealllistenersofyourstationwillconnect.Thesourceclient(ingeneral)runs onaseparatemachinethanicecast,butdoesnotnecessarilyneedto.Sourceclientssendthecontenttoicecastand providethestreamdata(encodedaudio)thatisthenrelayedouttolistenersbyicecast. Itisimportanttonotethatnotallsourceclientsworkwithicecast2.Youwillneedtochecktomakesurethat icecast2issupportedbyyourchosensourceclient. TheBasics Eachicecastservercanhousemultiplebroadcasts(ormountpoints)eachcontainingaseparatestreamofcontent. A'mountpoint'isauniquenameonyourserveridentifyingaparticularstreamitlookslikeafilename,suchas '/stream.ogg'.Alistenercanonlylistentoasinglemountpointatatime.Thismeansyoucanhaveasingleicecast servercontaineithermultiplebroadcastswithdifferentcontent,orpossiblythesamebroadcastbutwithstreamsof differentbitratesorqualities.Inthiscaseeachbroadcastorstreamisaseparatemountpoint. Atthispoint,thestepsoutlinedhererelatedtotheUnixversionorWin32consoleversionoficecast.Icecastisalso availableinaWin32GUIversion,andthestepsaresimilarinsetup,butnotquitethesame. Thefirststepintheprocessistofindandinstalltheicecast2serveritself.Howtodothisisnotcontainedwithin thisdocumentation.Afterinstallationyoushouldhaveandicecastbinaryand3directories confContainstheicecastconfigurationfile(icecast.xml)whichdefinesalltheconfigurationparametersforthe server. admin Contains xslt files which are used by the icecast server to provide a webbased front end to the administrationcapabilitiesoftheserver. logsThisisablankdirectorywhich(ifspecifiedintheconfigfile)willcontainallthelogs(thereare2)for icecast. Thenextstepistoedittheicecast.xmlfileandsettheappropriatevalues.Mostofthespecifiedvaluesinthe samplesarefine,forabasicsetupthefollowingentriesshouldbespecified,andifneccessary,changedtosuite yoursituation: <hostname>DNSnameorIPaddressusedforstreamdirectorylistings. <sourcepassword>willbeusedforthesourceclientauthentication <adminpassword>willbeusedforauthenticatingadminfeaturesoficecast <listensocket>(bothportandbindaddress) <logdir>directorywherelogfileswillbeplaced <webroot>directoryfornonadmincontent(fileservingroot),statuspageisprovided <adminroot>directorycontainingadminxsltfiles Mostwillnotneedtochangeadminroot/webrootasthoseareonlyreadbyicecastbuticecastneedstocreatefiles inthelogdirwhichMAYmeanyouwanttobemoreselective.Theothersettingsabovewillneedtobeprovidedby theicecastadministrator Oncetheconfigurationfileismodified,youshouldbeabletostarttheserverwiththefollowingcommand

icecastc/path/to/icecast.xml If no error messages are generated, then check the error.log file for the 'server started' message, it will look somethinglike: [2003103113:04:49]INFOmain/main.cIcecast2.3.0serverstarted Youmaynoticeslightvariationstothelineabove,thetimewillnodoubtbedifferent,andonsomeplatformsthe main.cisjustmain,butthekeythinghereisthattheserverisstarted,loggingisworkingandtheversionisshown. YoucanalsoverifythatitstartedbyvisitingthefollowingURL:http://yourip:port/admin/stats.xml.Youshould be prompted for a username and password. Enter the username "admin" and the password you entered for <adminpassword>.Ifalliswell,youshouldseeansmallXMLtreewhichrepresentsicecaststatistics(moreabout thatlater). Nowthattheicecastserverisstartedyoumustnowconfigureyoursourceclient.Theinformationyouwillneed forthesourceclientisthefollowing: IPaddressandPortoftheicecastserverbothofthesecomefrom<listensocket> sourcepasswordfrom<sourcepassword> Additionally,youwillneedtochooseamountpointandspecifythisinthesourceclient.Icecastdoesnotneedto knowabouteachmountpoint(althoughyoucanconfiguresettingsforspecificmountpointthisiscoveredunder Advanced configuration) there are, however, some points to mention regarding mountpoints. All Ogg Vorbis streamsshouldhavemountpointsthatendin.ogg(i,e./mystream.ogg).Thisisduetothelazywaymostmedia playersinferthetypeofstream.MP3streamsusuallydonotcontainanextension(/mystream).Mountpointsalso shouldnotcontainanyspacesoroddcharacters(againduetothelazywaymanyofthemediaplayersarecoded). Onceyouhaveconfiguredyoursourceclient,youshouldbeabletoconnectittotheicecastserver.Verifythatitis connectedbyhittingthestats.xmlURLthatwasmentionedabove. Now that you have the source connnected, listening to the stream involves simply opening the appropriate followingURLinabrowser:http://yourip:port/mounpointyouspecified.m3u.So,forinstance,ifyouattachedyour sourceclienttoanicecastserverlocatedat192.168.1.10:8000withamountpointof/mystream.ogg,thenyou wouldopen:http://192.168.1.10:8000/mystream.ogg.m3u.Notethatthe.m3uextentionwillserveupalinkthat opensmostmediaplayers.Alsoitisimportanttonotethatm3uneednotcontainonlyMP3stream,itcancontain streams of arbitrary contenttype and is used by icecast to serve a playlist that represents your broadcast to listening clients. Alternatively you can open up the stream URL directly within your media player (http://192.168.1.10:8000/mystream.ogginthiscase)

ConfigFile Overview Thissectionwilldescribeeachsectionoftheconfigfileandisgroupedintothefollowingsections: Limits Authentication StreamDirectorySettings MiscServersettings Relaysettings MountSpecificsettings Filepathsettings Logging Security Limits <limits> <clients>100</clients> <sources>2</sources> <queuesize>102400</queuesize> <clienttimeout>30</clienttimeout> <headertimeout>15</headertimeout> <sourcetimeout>10</sourcetimeout> <burstonconnect>1</burstonconnect> <burstsize>65536</burstsize> </limits> Thissectioncontainsserverlevelsettingsthat,ingeneral,donotneedtobechanged.Onlymodifythissectionif youareknowwhatyouaredoing. clients Totalnumberofconcurrentclientssupportedbytheserver.Listenersareconsideredclients,butsoareaccessesto any static content(i.e. fileserved content) and also anyrequeststo gatherstats. Thesearemax*concurrent* connectionsfortheentireserver(notpermountpoint). sources Maximumnumberofconnectedsourcessupportedbytheserver.Thisincludesactiverelaysandsourceclients. queuesize Thisisthemaximumsize(inbytes)ofthestreamqueue.Alistenermaytemporarilylagbehindduetonetwork congestionandinthiscaseaninternalqueueismaintainedforthelisteners.Ifthequeuegrowslargerthanthis configvalue,thenitistruncatedandanylistenersfoundwillberemovedfromthestream. Thiswillbethedefaultsettingforthestreamswhichis512kunlessoverriddenhere.Youcanoverridethisinthe individualmountsettingswhichcanbeusefulifyouhaveamixtureofhighbandwidthvideoandlowbitrateaudio streams. clienttimeout Thisdoesnotseemtobeused.

headertimeout Themaximumtime(inseconds)towaitforarequesttocomeinoncetheclienthasmadeaconnectiontothe server.Ingeneralthisvalueshouldnotneedtobetweaked. sourcetimeout Ifaconnectedsourcedoesnotsendanydatawithinthistimeoutperiod(inseconds),thenthesourceconnection willberemovedfromtheserver. burstonconnect Thissettingisreallyjustanaliasforburstsize.Whenenabledtheburstsizeis64kbytesanddisabledtheburst sizeis0kbytes.Thisoptionisdeprecated,useburstsizeinstead. burstsize Theburstsizeistheamountofdata(inbytes)tobursttoaclientatconnectiontime.Likeburstonconnect,thisis toquicklyfilltheprebufferusedbymediaplayers.Thedefaultis64kbyteswhichisatypicalsizeusedbymost clientssochangingitisnotusuallyrequired.Thissettingappliestoallmountpointsunlessoverriddeninthe mountsettings. Authentication <authentication> <sourcepassword>hackme</sourcepassword> <relayuser>relay</relayuser> <relaypassword>hackme</relaypassword> <adminuser>admin</adminuser> <adminpassword>hackme</adminpassword> </authentication> Thissectioncontainsalltheusernamesandpasswordsusedforadministrationpurposesortoconnectsourcesand relays. sourcepassword Theunencryptedpasswordusedbysourcestoconnecttoicecast2.Thedefaultusernameforallsourceconnections is'source'butthisoptionallowstospecifyadefaultpassword.Thisandtheusernamecanbechangedinthe individualmountsections. relayuser Usedinthemasterserveraspartoftheauthenticationwhenaslaverequeststhelistofstreamstorelay.The defaultusernameis'relay' relaypassword Usedinthemasterserveraspartoftheauthenticationwhenaslaverequeststhelistofstreamstorelay. adminuser adminpassword Theusername/password used foralladministration functions. This includes retrievingstatistics, accessingthe webbasedadministrationscreens,etc.Alistofthesefunctionscanbefoundinthe"Administration"sectionofthe

manual. StreamDirectorySettings <directory> <ypurltimeout>15</ypurltimeout> <ypurl>http://dir.xiph.org/cgibin/ypcgi</ypurl> </directory> ThissectioncontainsallthesettingsforlistingastreamonanyoftheIcecast2YPDirectoryservers.Multiple occurrencesofthissectioncanbespecifiedinordertobelistedonmultipledirectoryservers. ypurltimeout This value is the maximum time icecast2 will wait for a response from a particular directory server. The recommendedvalueshouldbesufficientformostdirectoryservers. ypurl TheURLwhichicecast2usestocommunicatewiththeDirectoryserver.Thevalueforthissettingisprovidedby theowneroftheDirectoryserver. MiscServerSettings Serverwidesettings. <hostname>localhost<hostname> <fileserve>1</fileserve> <serverid>icecast2.3</serverid> hostname ThisistheDNSnameorIPaddressthatwillbeusedforthestreamdirectorylookupsorpossibilytheplaylist generation if a Host header is not provided. While localhost is shown as an example, in fact you will want somethingthatyourlistenerscanuse. fileserve Thisflagturnsontheicecast2fileserverfromwhichstaticfilescanbeserved.Allfilesareservedrelativetothe pathspecifiedinthe<paths><webroot>configurationsetting.Bydefaultthesettingisenabledsothatrequests fortheimagesonthestatuspageareretrievable. serverid Thisoptionalsettingallowsfortheadministratoroftheservertooverridethedefaultserveridentification.The defaultisicecastfollowedbyaversionnumberandmostwillnotcaretochangeithoweverthissettingwill changethat. Thefollowingshowshowyoucanspecifythelisteningsettingsfortheserver. Thefirstshowsanexampleofacommonandsimplewaytodefinealisteningsocket <listensocket> <port>8000</port> </listensocket>

Usingthisasabasiswecanextendthiswithan<bindaddress>settingtolimitwhichaddressicecastwilllisten on.Mostwillnotneedtousebindaddressandoftengetconfusedbyusingitwhenthereisnoneed.Another possibilityistousean<ssl>booleansettingwhichinformsicecastthatasecuredconnectionistobeused.A commonuseforusingasecureconnectionwouldbeforadminpageaccess. Thefollowingshowshowwecanextendasinglelistensockettoworkwithshoutcaststylesourceclients.There aretwoissuesshoutcastsourceclientshaveovericecastsourceclients,oneisthelackofmountpointandthe secondistherequirementoftwoports.Bothoftheseissuesarehandledbyasimpleadditioninthelistensocket. <listensocket> <port>8000</port> <shoutcastmount>/live.mp3</shoutcastmount> </listensocket> Asbeforetheportspecifiedisallocatedbutthistimetheshoutcastmountimplicitydefinesasecondlistening socket whose port number is always one higher than the port defined, this also informs icecast of which mountpointtheshoutcastsourceclientonthissocketwillbeusing.Usingthisapproachyoucanallowmultiple shoutcastsourceclientstoconnectatthesametime. Thefollowingisjusttoshowthelongerapproachtodefiningshoutcastcompatability. <shoutcastmount>/live.nsv</shoutcastmount> <Youmayhavemultiple<listensocket>elements> <listensocket> <port>8000</port> </listensocket> <listensocket> <port>8001</port> <shoutcastcompat>1</shoutcastcompat> </listensocket> Notethatmultiplelistensocketsectionsmaybeconfiguredinordertohaveicecast2listenonmultiplenetwork interfacesormultipleports.Ifabindaddressisnotspecifiedforaparticularlistensocket,thenthesocketwillbe boundtoallinterfaces(includingIPv6ifavailable).Formostpeople,thebindaddressoptionwillnotberequired andoftenconfusespeople. port TheTCPportthatwillbeusedtoacceptclientconnections. bindaddress AnoptionalIPaddressthatcanbeusedtobindtoaspecificnetworkcard.Ifnotsupplied,thenitwillbindtoall interfaces. shoutcastmount AnoptionalmountpointsettingtobeusedwhenshoutcastDSPcompatibleclientsconnect.Thedefaultglobal settingis/streambutcanbeoverriddenheretouseanalternativenamewhichmayincludeanextensionthat someclientsrequireforcertainformats. Definingthiswithinalistensocketgrouptellsicecastthatthisportandthesubsequentportaretobeusedfor shoutcast compatiblesourceclients. This isan alternative to theshoutcastcompat approach as this implicitly defines thesecond listening socket and allowsfor specifying multiple sockets using different mountpoints for

shoutcast source clients. The shoutcastmount outside of a listensocket group is the global setting of the mountpointtouse. shoutcastcompat This optional flag will indicate that this port will operate in 'shoutcastcompatibility' mode. Due to major differencesinthesourceclientconnectionprotocol,ifyouwishtouseanyoftheshoutcastDJtools,youwillneed toconfigureatleastonesocketasshoutcastcompatible.Notethatwheninthismode,onlysourceclients(and specificallyshoutcastsourceclients)willbeabletoattachtothisport.Alllistenersmayconnecttoanyoftheports definedwithoutthisflag.Also,forproperShoutcastDSPcompatibility,youmustdefinealistensocketwithaport onelessthantheonedefinedas'shoutcastcompat'.Thismeansifyoudefine8001asshoutcastcompat,thenyou willneedtodefinealistenportof8000anditmustnotalsobedefinedasshoutcastcompat.Seetheexample configfileinthedistributionformoreinfo. RelayingStreams This section contains the servers relay settings. The relays are implemented using a pull system where the receivingserverconnectsasifitsalistenertothesendingserver.Therearetwotypesofrelaysetups:a"Master serverrelay"ora"SpecificMountpointrelay." MasterRelay AMasterserverrelayisonlysupportedbetweenicecast2serversandisusedtorelayanumberofmountpoints fromaremoteicecast2server. <masterserver>127.0.0.1</masterserver> <masterserverport>8001</masterserverport> <masterupdateinterval>120</masterupdateinterval> <masterusername>relay</masterusername> <masterpassword>hackme</masterpassword> <relaysondemand>0</relaysondemand> ThefollowingdiagramshowsthebasicsofusingaMasterrelay.Pleasenotethattheslaveisconfiguredwiththe <masterserver>,<masterserverport>,etcsettingsandthemasteristheicecastserverfromwhichtheslavewill pullmountpointsandrelaythem.UsingaMasterserverrelay,allnonhiddenmountpointsonthemastercanbe relayedusingthismechanism. A server is configured as a Master Server relay by specifying the <masterserver>, <masterserver port>,<masterupdateinterval>,<masterpassword>valuesintheconfigfile.Theserverthatisbeingrelayed doesnotneedanyspecialconfiguration. masterserver ThisistheIPfortheserverwhichcontainsthemountpointstoberelayed(MasterServer). masterserverport ThisistheTCPPortfortheserverwhichcontainsthemountpointstoberelayed(MasterServer). masterupdateinterval Theinterval(inseconds)thattheRelayServerwillpolltheMasterServerforanynewmountpointstorelay. masterusername

Thisistherelayusernameonthemasterserver.Itisusedtoquerytheserverforalistofmountpointstorelay.If notspecifiedthen'relay'isused. masterpassword ThisistherelaypasswordontheMasterserver.Itisusedtoquerytheserverforalistofmountpointstorelay. relaysondemand Globalondemandsettingforrelays.Becauseyoudonothaveindividualrelayoptionswhenusingamasterserver relay,youstillmaywantthoserelaystoonlypullthestreamwhenthereisatleastonelistenerontheslave.The typicalcasehereistoavoidsurplusbandwidthcostswhennooneislistening. SpecificMountpointRelay Ifonlyspecificmountpointsneedtoberelayed,thenyoucanconfigureIcecastwitha"SpecificMountpointRelay". NotethattherelayingIcecastisconfiguredwiththe<relay>settingsandwillpullthespecifiedmountpoint(s) and relay them to the listeners. Using a Specific Mountpoint Relay, only those mountpoints specified will be relayed. Specific Mountpoint Relays can be configured to relay from an Icecast 2 server, as well as Icecast 1.x and Shoutcast.AserverisconfiguredasaSpecificMountpointServerrelaybyspecifyinga<relay>XMLchunkinthe config file for each mountpoint to be relayed. The server that is being relayed does not need any special configuration. <relay> <server>127.0.0.1</server> <port>8001</port> <mount>/example.ogg</mount> <localmount>/different.ogg</localmount> <username>joe</username> <password>soap</password> <relayshoutcastmetadata>0</relayshoutcastmetadata> <ondemand>1</ondemand> </relay> server ThisistheIPfortheserverwhichcontainsthemountpointtoberelayed. port ThisistheTCPPortfortheserverwhichcontainsthemountpointtoberelayed. mount The mountpoint located on the remote server. If you are relaying a shoutcast stream, this should be a '/' or '/;name'. localmount Thenametouseforthelocalmountpoint.Thisiswhatthemountwillbenamedontherelayingserver.Bydefault theremotemountpointnameisused. username

Thesourceoftherelaymayrequireauthenticationitself,ifsostatetheusernamehere. password Thesourceoftherelaymayrequireauthenticationitself,ifsostatethepasswordhere. relayshoutcastmetadata IfyouarerelayingaShoutcaststream,youmaywanttospecifythisindicatortoalsorelaythemetadata(song titles)thatarepartoftheShoutcastdatastream(1=enabled,0=disabled).Bydefaultthisisenabledbutitisupto theremoteserveronwhetheritsendsany. ondemand An ondemand relay will only retrieve the stream if there are listeners requesting the stream. 1=enabled, 0=disabled(defaultis<relaysondemand>).Thisisusefulincaseswhereyouwanttolimitbandwidthcosts whennooneislistening. MountSpecificSettings <mount> <mountname>/examplecomplex.ogg</mountname> <username>othersource</username> <password>hackmemore</password> <maxlisteners>1</maxlisteners> <maxlistenerduration>3600</maxlistenerduration> <dumpfile>/tmp/dumpexample1.ogg</dumpfile> <intro>/intro.ogg</intro> <fallbackmount>/example2.ogg</fallbackmount> <fallbackoverride>1</fallbackoverride> <fallbackwhenfull>1</fallbackwhenfull> <charset>ISO88591</charset> <public>1</public> <streamname>Myaudiostream</streamname> <streamdescription>Myaudiodescription</streamdescription> <streamurl>http://some.place.com</streamurl> <genre>classical</genre> <bitrate>64</bitrate> <type>application/ogg</type> <subtype>vorbis</subtype> <hidden>1</hidden> <burstsize>65536</burstsize> <mp3metadatainterval>4096</mp3metadatainterval> <authenticationtype="htpasswd"> <optionname="filename"value="myauth"/> <optionname="allow_duplicate_users"value="0"/> </authentication> <onconnect>/home/icecast/bin/sourcestart</onconnect> <ondisconnect>/home/icecast/bin/sourceend</ondisconnect> </mount> Thissectioncontainsthesettingswhichapplyonlytoaspecificmountpointandappliestoanincomingstream whetheritisarelayorasourceclient.Thepurposeofthemountdefinitionistostatecertaininformationthatcan overrideeitherglobal/defaultsettingsorsettingsprovidedfromtheincomingstream.

Amountdoesnotneedtobestatedforeachincomingsourcealthoughyoumaywanttospecificcertainsettings likethemaximumnumberoflistenersoramountpointspecificusername/password.Asageneralrule,onlydefine whatyouneedtobuteachmountdefinitionneedsatleastthemountname.Changestomostofthesewillapply acrossaconfigurationfilerereadevenonactivestreams,howeversomeonlyapplywhenthestreamstartsor ends. mountname Thenameofthemountpointforwhichthesesettingsapply. username Anoptionalvaluewhichwillsettheusernamethatasourcemustusetoconnectusingthismountpoint. password Anoptionalvaluewhichwillsetthepasswordthatasourcemustusetoconnectusingthismountpoint. maxlisteners Anoptionalvaluewhichwillsetthemaximumnumberoflistenersthatcanbeattachedtothismountpoint. maxlistenerduration Anoptionalvaluewhichwillsetthelengthoftimealistenerwillstayconnectedtothestream.Anauthcomponent mayoverridethis. dumpfile An optional value which will set the filename which will be a dump of the stream coming through on this mountpoint. intro Anoptionalvaluewhichwillspecifythefilethosecontentswillbesenttonewlistenerswhentheyconnectbut beforethenormalstreamissent.Makesuretheformatofthefilespecifiedmatchesthestreamingformat.The specifiedfileisappendedtowebrootbeforebeingopened. fallbackmount Thisoptionalvaluespecifiesamountpointthatclientsareautomaticallymovedtoifthesourceshutsdownoris notstreamingatthetimealistenerconnects.Onlyonecanbelistedineachmountandshouldrefertoanother mountpointonthesameserverthatisstreaminginthesamestreamingformat. Ifclientscannotfallbacktoanothermountpoint,duetoamissingfallbackmountoritstatesamountpointthatis justnotavailable,thenthoseclientswillbedisconnected.Ifclientsarefallingbackto amountpointandthe fallbackmountisnotactivelystreamingbutdefinesafallbackmountitselfthenthoseclientsmaybemovedthere instead.Thismultilevelfallbackallowsclientstocascadeseveralmountpoints. Afallbackmountcanalsostateafilethatislocatedinwebroot.Thisisusefulforplayingaprerecordedfileinthe caseofastreamgoingdown.Itwillrepeatuntileitherthelistenerdisconnectsorastreamcomesbackavailable andtakesthelistenersback.Asperusual,thefileformatshouldmatchthestreamformat,failingtodosomay causeproblemswithplayback. Notethatthefallbackfileisnottimedsobecarefulifyouintendtorelaythis.Theyarefineonslavestreamsbut don'tusethemonmasterstreams,ifyoudothentherelaywillconsumestreamdataatafasterrateandthe

listenersontherelaywouldeventuallygetkickedoff. fallbackoverride Whenenabled,thisallowsaconnectingsourceclientorrelayonthismountpointtomovelisteningclientsback fromthefallbackmount. fallbackwhenfull Whensetto1,thiswillcausenewlisteners,whenthemaxlistenercountforthemountpointhasbeenreached,to movetothefallbackmountifthereisonespecified. noyp(deprecated) SettingthisoptionpreventsthismountpointfromadvertisingonYP .Thedefaultis0soYPadvertisingcanoccur howeveryoumaywanttopreventithereifyouintendlistenerstoconnecttoalocalrelayinstead.Deprecated option,replacedby<public> charset FornonOggstreamslikeMP3,themetadatathatisinsertedintothestreamoftenhasnodefinedcharacterset.We havetraditionallyassumedUTF8asitallowsformultiplelanguagesetsonthewebpagesandstreamdirectory, howevermanysourceclientsforMP3typestreamshaveassumedLatin1(ISO88591)orleaveittowhatever charactersetisinuseonthesourceclientsystem. Thischaractermismatchhasbeenknowntocauseaproblemasthestatsengineandstreamdirectoryserverswant UTF8 so now we assume Latin1 for nonOgg streams (to handle the common case) but you can specify an alternativecharactersetwiththisoption. Thesourceclientscanalsospecifyacharset=parametertothemetadataupdateURLiftheysowish. public Thedefaultsettingforthisis1indicatingthatitisuptothesourceclientorrelaytodetermineifthismountpoint shouldadvertise.Asettingof0willpreventanyadvertisingandasettingof1willforceittoadvertise.Ifyoudo forceadvertisingyoumayneedtosetothersettingslistedbelowastheYPservercanrefusetoadvertiseifthereis notenoughinformationprovided. streamname Settingthiswilladdthespecifiednametothestats(andthereforeYP)forthismountpointevenifthesource client/relayprovideone. streamdescription Settingthiswilladdthespecifieddescriptiontothestats(andthereforeYP)forthismountpointevenifthesource client/relayprovideone. streamurl SettingthiswilladdthespecifiedURLtothestats(andthereforeYP)forthismountpointevenifthesource client/relayprovideone.TheURLisgenerallyfordirectingpeopletoawebsite. genre Settingthiswilladdthespecifiedgenretothestats(andthereforeYP)forthismountpointevenifthesource client/relayprovideone.ThiscanbeanythingbeusingcertainkeywordscanhelpsearchesintheYPdirectories.

bitrate Settingthiswilladdthespecifiedbitratetothestats(andthereforeYP)forthismountpointevenifthesource client/relayprovideone.Thisisstatedinkbps. type Settingthiswilladdthespecifiedmimetypetothestats(andthereforeYP)forthismountpointevenifthesource client/relayprovideone.Itisveryunlikelythatthiswillbeneeded. subtype Settingthiswilladdthespecifiedsubtypetothestats(andthereforeYP)forthismountpoint.Thesubtypeisreally tohelptheYPservertoidentifythecomponentsofthetype.Anexamplesettingisvorbis/theoradoindicatethe codecsinanOggstream burstsize Thisoptionalsettingallowsforprovidingaburstsizewhichoverridesthedefaultburstsizeasdefinedinlimits. Thevalueisinbytes. mp3metadatainterval This optional setting specifies what interval, in bytes, there is between metadata updates within shoutcast compatiblestreams.Thisonlyappliestonewlistenersconnectingonthismountpoint,notexistinglistenersfalling backtothismountpoint.Thedefaultiseitherthehardcodedserverdefaultorthevaluepassedfromarelay. hidden Enablethistopreventthismountfrombeingshownonthexslpages.Thisismainlyforcaseswherealocalrelayis configuredandyoudonotwantthesourceofthelocalrelaytobeshown authentication Thisspecifiesthatthenamedmountpointwillrequirelistenerauthentication.Currently,weonlysupportafile basedauthenticationscheme(type=htpasswd).Usersandencryptedpasswordareplacedinthisfile(separatedby a:)andallrequestsforthismountpointwillrequirethatauserandpasswordbesuppliedforauthentication purposes. These values are passed in via normal HTTP Basic Authentication means (i.e. http://user:password@stream:port/mountpoint.ogg). Users and Passwords are maintained via the web admin interface.Amountpointconfiguredwithanauthenticatorwilldisplayaredkeynexttothemountpointnameon theadminscreens.Youcanreadmoreaboutlistenerauthenticationhere. onconnect State a program that is run when the source is started. It is passed a parameter which is the name of the mountpointthatisstarting.Theprocessingofthestreamdoesnotwaitforthescripttoend.Thisoptionisnot availableonwin32 ondisconnect Stateaprogramthatisrunwhenthesourceends.Itispassedaparameterwhichisthenameofthemountpoint thathasended.Theprocessingofthestreamdoesnotwaitforthescripttoend.Thisoptionisnotavailableon win32 PathSettings

<paths> <basedir>./</basedir> <logdir>./logs</logdir> <pidfile>./icecast.pid</pidfile> <webroot>./web</webroot> <adminroot>./admin</adminroot> <allowip>/path/to/ip_allowlist</allowip> <denyip>/path_to_ip_denylist</denyip> <aliassource="/foo"dest="/bar"/> </paths> Thissectioncontainspathswhichareusedforvariousthingswithinicecast.Allpaths(otherthananyaliases) shouldnotendina'/'. basedir Thispathisusedinconjunctionwiththechrootsettings,andspecifiedthebasedirectorythatischrootedtowhen theserverisstarted.Thisfeatureisnotsupportedonwin32. logdir Thispathspecifiesthebasedirectoryusedforlogging.Boththeerror.logandaccess.logwillbecreatedrelativeto thisdirectory. pidfile Thispathnamespecifiesthefiletowriteatstartupandtoremoveatnormalshutdown.Thefilecontainsthe processidoftheicecastprocess.Thiscouldbereadandusedforsendingsignalsicecast. webroot Thispathspecifiesthebasedirectoryusedforallstaticfilerequests.Thisdirectorycancontainallstandardfile types(includingmp3sandoggvorbisfiles).Forexample,ifwebrootissetto/var/share/icecast2,andarequest forhttp://server:port/mp3/stuff.mp3comesin,thenthefile/var/share/icecast2/mp3/stuff.mp3willbeserved. adminroot Thispathspecifiesthebasedirectoryusedforalladminrequests.Morespecifically,thisisusedtoholdtheXSLT scriptsused forthewebbasedadmin interface. Theadmindirectory contained within theicecast distribution containsthesefiles. allowip Ifspecified,thisspecifiesthelocationofafilethatcontainsalistofIPaddressesthatwillbeallowedtoconnectto icecast.Thiscouldbeusefulincaseswhereamasteronlyfeedsknownslaves.Theformatofthefileissimple,one IPperline. denyip If specified, this specifies the location of a file that contains a list of IP addressess that will be dropped immediately.Thisismainlyforproblemclientswhenyouhavenoaccesstoanyfirewallconfiguration.Theformat ofthefileissimple,oneIPperline. aliassource="/foo"dest="/bar" Aliasesareusedtoprovideawaytocreatemultiplemountpointsthatrefertothesamemountpoint.

LoggingSettings <logging> <accesslog>access.log</accesslog> <errorlog>error.log</errorlog> <playlistlog>playlist.log</playlistlog> <loglevel>4</loglevel><4Debug,3Info,2Warn,1Error> </logging> Thissectioncontainsinformationrelatingtologgingwithinicecast.Therearetwologfilescurrentlygeneratedby icecast,anerror.log(wherealllogmessagesareplaced)andanaccess.log(whereallstream/admin/httprequests arelogged). Notethatonnonwin32platforms,aHUPsignalcanbesenttoicecastinwhichthelogfilesarereopenedfor appendinggivingtheabilitymove/removethelogfiles. accesslog Intothisfile,allrequestsmadetotheicecast2willbelogged.Thisfileisrelativetothepathspecifiedbythe <logdir>configvalue. errorlog Allicecastgeneratedlogmessageswillbewrittentothisfile.Iftheloglevelissettoohigh(Debugforinstance) thenthisfilecangrowfairlylargeovertime.Currently,thereisnologrotationimplemented. playlistlog Intothisfile,alogofallmetadataforeachmountpointwillbewritten.Theformatofthelogfilewillmostlikely changeovertimeaswenarrowinonastandardformatforthis.Currently,thefileispipedelimited.Thisoptionis optionalandcanberemovedentirelyfromtheconfigfile. logsize Thisvaluespecifies(inKbytes)themaxmimumsizeofanyofthelogfiles.Whenthelogfilegrowsbeyondthis value,icecastwilleitherrenameittologfile.old,oraddatimestamptothearchivedfile(iflogarchiveisenabled). logarchive Ifthisvalueisset,thenicecastwillappendatimestamptotheendofthelogfilenamewhenlogsizehasbeen reached.Ifdisabled,thenthedefaultbehavioristorenamethelogfiletologfile.old(overwritinganypreviously savedlogfiles).Wedisablethisbydefaulttopreventthefillingupoffilesystemsforpeoplewhodon'tcare(or know)thattheirlogsaregrowing. loglevel Indicateswhatmessagesareloggedbyicecast.Logmessagesarecategorizedintooneof4types,Debug,Info, Warn,andError. Thefollowingmappingcanbeusedtosettheappropriatevalue: loglevel=4Debug,Info,Warn,Errormessagesareprinted loglevel=3Info,Warn,Errormessagesareprinted loglevel=2Warn,Errormessagesareprinted loglevel=1Errormessagesonlyareprinted

SecuritySettings <security> <chroot>0</chroot> <changeowner> <user>nobody</user> <group>nogroup</group> </changeowner> </security> Thissectioncontainsconfigurationsettingsthatcanbeusedtosecuretheicecastserverbyperformingachrootto asecuredlocation.Thisiscurrentlynotsupportedonwin32. chroot Anindicatorwhichspecifieswhetherachroot()willbedonewhentheserverisstarted.Thechrootedpathis specifiedbythe<basedir>configurationvalue. changeowner Thissectionindicatestheuserandgroupthatwillowntheicecastprocesswhenitisstarted.Theseneedtobe validusersonthesystem.

AdminInterface Overview This section contains information about the admin interface of icecast. Through this interface the user can manipulatemanyserverfeatures.Fromityoucangatherstatistics,movelistenersfrommountpointtomountpoint, disconnect connected sources, disconnect connected listeners, and many other activities. Each function is enumeratedhereaswellasanexampleusageofthefunction. EachofthesefunctionsrequiresHTTPauthenticationviatheappropriateusernameandpassword.Formount specificfunctions,youmayuseeitherthe<adminusername>and<adminpassword>specifiedintheicecast config file, or the username and password specified for that mountpoint (if any). For general functions (not specifictoasinglemountpoint),youmustusetheadminusernameandpassword.Itisalsoimportanttonotethat inalltheexamples192.168.1.10isusedastheexamplehostand8000isusedastheexampleportfortheicecast server. AdminFunctions(MountSpecific) Alltheseadminfunctionsaremountspecificinthattheyonlyapplytoaparticularmountpoint(asopposedto applyingtotheentireserver).Eachofthesefunctionsrequiresamountpointtobespecifiedasinput. MetadataUpdate Description: This function provides the ability for either a source client or any external program to update the metadata informationforaparticularmountpoint. Example: http://192.168.1.10:8000/admin/metadata?mount=/mystream&mode=updinfo&song=ACDC+Back+In+Black FallbackUpdate Description: This function provides the ability for either a source client or any external program to update the "fallback mountpoint"foraparticularmountpoint.Fallbackmountsarethosethatareusedintheevenofasourceclient disconnection. If a source client disconnects for some reason that all currently connected clients are sent immediatelytothefallbackmountpoint. Example: http://192.168.1.10:8000/admin/fallbacks?mount=/mystream.ogg&fallback=/myfallback.ogg ListClients Description: Thisfunctionlistsalltheclientscurrentlyconnectedtoaspecificmountpoint.TheresultsaresentbackinXML form. Example: http://192.168.1.10:8000/admin/listclients?mount=/mystream.ogg MoveClients(Listeners) Description: Thisfunctionprovidestheabilitytomigratecurrentlyconnectedlistenersfromonemountpointtoanother.This

function requires 2 mountpoints to be passed in: mount (the *from* mountpoint) and destination (the *to* mountpoint). After processing this function all currently connected listeners on mount will be connected to destination.Notethatthedestinationmountpointmustexistandhaveasounceclientalreadyfeedingitastream. Example: http://192.168.1.10:8000/admin/moveclients?mount=/mystream.ogg&destination=/mynewstream.ogg KillClient(Listener) Description: Thisfunctionprovidestheabilitytodisconnectaspecificlistenerofacurrentlyconnectedmountpoint.Listeners areidentifiedbyauniqueidthatcanberetrievedbyviathe"ListClients"adminfunction.Thisidmustbepassed intotherequest.Afterprocessingthisrequest,thelistenerwillnolongerbeconnectedtothemountpoint. Example: http://192.168.1.10:8000/admin/killclient?mount=/mystream.ogg&id=21 KillSource Description: Thisfunctionwillprovidetheabilitytodisconnectaspecificmountpointfromtheserver.Themountpointtobe disconnectedisspecifiedviathevariable"mount". Example: http://192.168.1.10:8000/admin/killsource?mount=/mystream.ogg AdminFunctions(General) Stats Description: This admin function provides the ability to query the internal statistics kept by the icecast server. Almost all information about the internal workings of the server such as the mountpoints connected, how many client requestshavebeenserved,howmanylistenersforeachmountpoint,etc,areavailableviathisadminfunction. Notethatthisadminfunctioncanalsobeinvokedviathehttp://server:port/admin/stats.xmlsyntax,howeverthis syntaxshouldnotbeusedandwilleventuallybecomedeprecated. Example: http://192.168.1.10:8000/admin/stats ListMounts Description: Thisadminfunctionprovidestheabilitytoviewallthecurrentlyconnectedmountpoints. Example: http://192.168.1.10:8000/admin/listmounts WebBasedAdminInterface AsanalternativetomanuallyinvokingtheseURLs,awebbasedadmininterfacewasdeveloped.Thisinterface providesthesamefunctionsthatwereidentifiedanddescribedabovebutpresentstheminalittlenicerway.The WebBasedAdminInterfacetoicecastisshippedwithicecastprovidedinthe"admin"directoryandcomesreadyto use.Alltheuserneedstodoissetthepathtothisdirectoryintheconfigfileviathe<adminroot>configvariable.

TheWebBasedAdminInterfaceisaseriesofXSLTfileswhichareusedtodisplayalltheXMLobtainedviatheURL admininterface.Thiscanbechangedandmodifiedtosuittheuser'sneed.KnowledgeofXSLTandtransformations fromXMLtoHTMLarerequiredinordertomakechangestothesescripts. ThemainURLfortheWebBasedAdminInterfaceis http://192.168.1.10:8000/admin/stats.xsl FromthisURLalloftheotheradminfunctionscanbeexercised. ModificationofexistingXSLTtransformsin/adminisallowed,butnewfilescannotbecreatedhere.Creationof newXSLTtransformsaswellasmodificationofexistingtransformsisallowedin/web.Theseworkusingthe documentreturnedby/admin/stats.xml.ToseetheXMLdocumentthatisappliedtoeachadminXSLT,justchange the.xslto.xmlinyourrequest(i.e./admin/listclients.xml).YoucanthencodeyourXSLTtransformaccordingly.

ServerStatistics Overview Thissectioncontainsinformationabouttheserverstatisticsavailablefromicecast.AnexamplestatsXMLtreewill beshownandeachelementwillbedescribed.Thefollowingexamplestatstreewillbeused: <?xmlversion="1.0"?> <icestats> <client_connections>13</client_connections> <connections>14</connections> <source_connections>1</source_connections> <sources>1</sources> <sourcemount="/test.ogg"> <artist></artist> <audio_info>icesamplerate=32000;icebitrate=Quality1;icechannels=1</audio_info> <icebitrate>Quality1</icebitrate> <icechannels>1</icechannels> <icesamplerate>32000</icesamplerate> <listeners>0</listeners> <public>0</public> <title></title> <type>OggVorbis</type> </source> </icestats> GeneralStatistics clientconnections Clientconnectionsarebasicallyanythingthatisnotasourceconnection.Theseincludelisteners(notconcurrent, butcumulative),anyadminfunctionaccesses,andanystaticcontent(fileserving)accesses. sourceconnections Source connections arethe number of times (cumulative not currently connected) a source has connected to icecast. connections Thetotalofclient+sourceconnections. sources Thetotalofcurrentlyconnectedsources(mountpoints). SourceSpecificStatistics artist Artistofthecurrentsong(metadatasetbysourceclient). title

Titleofthecurrentsong(metadatasetbysourceclient). audioinfo Informationaboutthebitrate/samplerate/qualityofthestream(setbysourceclient).AlsousedforYPentries. icebitrate icesamplerate icechannels Informationaboutthebitrate/samplerate/qualityofthestream(setbysourceclient). listeners Thenumberofcurrentlyconnectedlisteners. public FlagthatindicateswhetherthismountisbeinglistedonaYP(seybysourceclient). type Mediatypeofthestream.

Relaying Overview Relayingistheprocessbywhichoneservermirrorsoneormorestreamsfromaremoteserver.Theserversneed notbeofthesametype(i.e.icecastcanrelayfromShoutcast).Relayingisusedprimarilyforlargebroadcaststhat needtodistributelisteningclientsacrossmultiplephysicalmachines. TypeOfRelays There aretwo typesofrelays thaticecast supports. Thefirsttypeiswhen bothmasterand slaveserversare icecast2servers.Inthiscase,a"masterslave"relaycanbesetupsuchthatallthatneedstobedoneisconfigurethe slaveserverwiththeconnectioninformation(serverip:port)ofthemasterserverandtheslavewillmirrorall mountpoints onthemaster server. Theslavewill also periodically check the masterserverto seeifany new mountpointshaveattachedandifsowillrelaythoseaswell.Thesecondtypeofrelayisa"singlebroadcast"relay. Inthiscase,theslaveserverisconfiguredwithaserverip+port+mountandonlythemountpointspecifiedis relayed.InordertorelayabroadcaststreamonaShoutcastserver,youmustusethe"singlebroadcast"relayand specifyamountpointof"/". SettingUpAMasterSlaveRelay Inordertosetuparelayofthistypebothservers(theoneyouwishtorelayandtheonedoingtherelaying)need tobeicecast2servers.Thefollowingconfigurationsnippetisusedasanexample: <masterserver>192.168.1.11</masterserver> <masterserverport>8001</masterserverport> <masterupdateinterval>120</masterupdateinterval> <masterpassword>hackme</masterpassword> Inthisexample,thisconfigurationissetupintheserverwhichwillbedoingtherelaying(slaveserver).Themaster serverinthiscaseneednotbeconfigured(andactuallyisunawareoftherelayingbeingperformed)asarelay. Whentheslaveserverisstarted,itwillconnecttothemasterserverlocatedat192.168.1.11:8001andwillbegin torelayallmountpointsconnectedtothemasterserver.Additionally,everymasterupdateinterval(120secondsin thiscase)theslaveserverwillpollthemasterservertoseeifanynewmountpointshaveconnected,andifso,the slaveserverwillrelaythoseaswell.Notethatthenamesofthemountpointsontheslaveserverwillbeidenticalto thoseonthemasterserver. SettingUpASingleBroadcastRelay Inthiscase,themasterserverneednotbeanicecast2server.Supportedmasterserversforasinglebroadcastrelay areShoutcast,Icecast1.x,andofcourseIcecast2.Thefollowingconfigurationsnippetisusedasanexample: <relay> <server>192.168.1.11</server> <port>8001</port> <mount>/example.ogg</mount> <localmount>/different.ogg</localmount> <relayshoutcastmetadata>0</relayshoutcastmetadata> </relay> Inthisexample,thisconfigurationisalsosetupintheserverwhichwillbedoingtherelaying(slaveserver).The masterserverinthiscaseneednotbeconfigured(andactuallyisunawareoftherelayingbeingperformed)asa

relay.Whentheslaveserverisstarted,itwillconnecttothemasterserverlocatedat192.168.1.11:8001andwill begintorelayonlythemountpointspecified(/example.ogginthiscase).Usingthistypeofrelay,theusercan overridethelocalmountpointnameandmakeitsomethingentirelydifferentthantheoneonthemasterserver. Additionally,iftheserverisaShoutcastserver,thenthe<mount>mustbespecifiedas/.Andifyouwantthe Shoutcastrelaystreamtohavemetadatacontainedwithinit(Shoutcastmetadataisembeddedinthestreamitself) thenthe<relayshoutcastmetadata>needstobesetto1.

ListingInAYPDirectories Overview A YP (Yellow Pages) directory is a listing of broadcast streams. Icecast2 has it own YP directory located at http://dir.xiph.org.Currentlyicecast2canonlybelistedinanicecast2supportedYPdirectory.Thismeansthatyou cannotlistyourstreamintheShoutcastYPdirectory. Intheicecast2configurationfileareallthecurrentlyavailableYPdirectoryservers.ListingyourstreaminaYPisa combinationofsettingsintheicecastconfigurationfileandalsoinyoursourceclient. ConfiguringIcecast2ForYPSupport Firstofall,icecastmusthavebeenbuiltwithYPsupport.Thisisautomaticallydoneifyouhavelibcurlinstalled.If libcurlisnotdetectedwhenicecatsiscompiled,thenYPsupportisdisabled. IficecasthasbeenbuiltwithYPsupport,thenthefollowingconfigurationoptionscontroltheYPdirectorysettings: <directory> <ypurltimeout>15</ypurltimeout> <ypurl>http://dir.xiph.org/cgibin/ypcgi</ypurl> </directory> MultipledirectoryXMLchunkscanbespecifiedinordertobelistedinmultipledirectories. ConfiguringYourSourceClientForYPSupport Thisisusuallycoveredinthesourceclientdocumentation.Morespecifically,thesourceclientneedstoprovidethe HTTPheadericepublic:1onconnectinordertoenableYPlistingofthestream. IfamountpointisbeinglistedonaYP ,thenyouwillseesomeadditionalstatisticsrelatingtotheYPsuchaslast touch,currentlyplaying,etc.

ListenerAuthentication ListenerAuthentication Listenerauthenticationisafeatureoficecastwhichallowsyoutosecureacertainmountpointsuchthatinorderto listen,alistenermustpasssomeverificationtest.Withthisfeature,asimplepayforplayoperation(eguser/pass), orsomefilteringbasedonthelistenerconnectioncanbeperformed.Thissectionwillshowyouthebasicsof settingupandmaintainingthiscomponent. Todefinelistenerauthentication,agroupoftagsarespecifiedinthe<mount>grouprelatingtothemountpoint. Thismeansthatauthenticationcanapplytolistenersofsourceclientsorrelays. Thefollowingauthenticationmechanismscanapplytolisteners HTPASSWDlookupanamedfileforamatchingusernameandpassword URLissuewebrequests(egPHP)tomatchauthentication ThelistenerauthenticationwithinaspecifiedmountintheicecastXMLconfigurationcanapplytoeithertoa streamfromasourceclient,relayorawebrootbasedfile.Theydoapplytointrofilesorfallbackstreams. HTPASSWDListenerAuthentication Inordertouselistenerauthentication,youMUSTconfigureamountspecificoption.Thismeansthatyouhaveto providea<mount>sectioninthemainicecastconfigfile.Thefollowingisanexample: <mount> <mountname>/example.ogg</mountname> <authenticationtype="htpasswd"> <optionname="filename"value="myauth"/> <optionname="allow_duplicate_users"value="0"/> </authentication> </mount> TosupportlistenerauthenticationyouMUSTprovideataminimum<mountname>and<authentication>.The mountnameisthenameofthemountpointthatyouwillusetoconnectyoursourceclientwithandauthentication configureswhattypeoficecast2authenticatortouse.Currently,onlyasingletype"htpasswd"isimplemented. Newauthenticatorswillbeaddedlater.Eachauthenticatorhasavariablenumberofoptionsthatarerequiredand thesearespecifiedasshownintheexample.Thehtpasswdauthenticatorrequiresafewparameters.Thefirst, filename,specifiesthenameofthefiletousetostoreusersandpasswords.Notethatthisfileneednotexist(and probablywillnotexistwhenyoufirstsetitup).Icecasthasbuiltinsupportformanagingusersandpasswordsvia thewebadmininterface.Moreonthislaterinthissection.Thesecondoption,allow_duplicate_users,ifsetto0, will prevent multiple connections using the same username. Setting this value to 1 will enable mutltiple connectionsfromthesameusernameonagivenmountpoint.Notethereisnowaytospecifya"maxconnections" foraparticularuser. Icecastsupportsamixtureofstreamsthatrequirelistenerauthenticationandthosethatdonot.Onlymountsthat arenamedintheconfigfilecanbeconfiguredforlistenerauthentication. ConfiguringUsersAndPasswords Oncetheappropriateentriesaremadetotheconfigfile,connectyoursourceclient(usingthemountpointyou namedintheconfigfile).Toconfigureusersandpasswordsforthisstreamyoumustusethewebbasedadmin interface.Navigatetohttp://server:ip/admin/stats.xsltobegin.Ifyouhaveconfiguredeverythingproperly,you

shouldseethispage(IcecastStatusPage):http://server:ip/admin/stats.xsl Youwillseealockinfrontofallmountpointconfiguredforlistenerauthentication.Alsonotethatthispagewill onlyshowCONNECTEDmountpoints. Tomanageusersandpasswordsforthismountpoint,clickonthelockorfollowthe"ManageAuthentication"link. Youshouldseethispage(ShowdefinedUsers). This screen will show all the users configured for this mountpoint. Adding users is as simple as entering a usernameandpasswordinthefieldsandclicking"AddNewUser".NotethatusernamesMUSTbeuniqueand thereareNOrestrictionsonpasswords.Youcandeleteusersbyclickingtheappropriatedeletelinknexttoeach user. FinishingItAllOff Ok,soyou'vecreatedyourusers,andyouhaveeverythingsetupproperly,howdoyouruserslogin?Well,we've provided a simple login form that you can use for this purpose. This page (Authorization Page) http://server:port/auth.xslwillbringupaformthatuserscanusetoentertheirusernameandpassword. Thispagewillserveam3uwiththeusernameandpasswordandinmostcasesshouldopenthecorrectmedia playerandbeginplayingyourstream URL AuthenticatinglistenersviatheURLmethodinvolvesicecast,whenalistenerconnects,issuingrequeststoaweb serverandcheckingtheresponseheaders.Ifacertainheaderissentbackthenthelistenerconnectingisallowedto continue,ifnot,anerrorissentbacktothelistener. TheURLsspecifiedwillinvokesomewebserverscriptslikePHPtodoanyworkthattheymaychoosetodo.All thatisrequiredofthescriptinglanguageisthatPOSTinformationcanbehandledandresponseheaderscanbe sentback. libcurl is used forthe requestingso httpsconnectionsmaybepossible, butbeaware oftheextra overheadinvolved. Theuseragentsentineachcurlrequestwillrepresenttheicecastserverversion.Theresponseheaderswilldepend onwhetherthelisteneristobeaccepted.Inthecaseofrejection,aresponseheader icecastauthmessage:reason shouldalsobereturnedforplacinginthelogfiles. InordertouseURLbasedlistenerauthentication,youMUSTconfigureamountspecificoption.Thismeansthat youhavetoprovidea<mount>sectioninthemainicecastconfigfile.Thefollowingshowsthelistofoptions available: <mount> <mountname>/example.ogg</mountname> <authenticationtype="url"> <optionname="mount_add"value="http://myauthserver.com/stream_start.php"/> <optionname="mount_remove"value="http://myauthserver.com/stream_end.php"/> <optionname="listener_add"value="http://myauthserver.com/listener_joined.php"/> <optionname="listener_remove"value="http://myauthserver.com/listener_left.php"/> <optionname="username"value="user"/> <optionname="password"value="pass"/> <optionname="auth_header"value="icecastauthuser:1"/>

<optionname="timelimit_header"value="icecastauthtimelimit:"/> </authentication> </mount> Theoptionsaredescribedbelowinmoredetail,eachofwhichisoptional,butineachcase,withinthePOSTdata, thevalueforeachsettingisencoded. mount_add ThisURLisforinformingtheauthserverofastreamstarting.Nolistenerinformationispassedforthis,butcanbe usedtoinitialiseanydetailstheauthservermayhave. POSTdetailsare action=mount_add&mount=/live&server=myserver.com&port=8000 Herethedetailsindicatetheservername(<hostname>)andmountpointstartingup mount_remove ThisURLisforinformingtheauthserverofastreamfinishing,likethestartoption,nolistenerdetailsarepassed. POSTdetailsare action=mount_remove&mount=/live&server=myserver.com&port=8000 likethestartoption,servernameandmountpointareprovided listener_add Thisismostlikelytobeusedifanything.Whenalistenerconnects,beforeanythingissentbacktothem,this requestisprocessed.Thedefaultactionistorejectalistenerunlesstheauthserversendsbackaresponseheader whichmaybestatedinthe'header'option POSTdetailsare action=listener_add&server=myserver.com&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&a gent="My%20player" Therearemoredetailswiththis,clientistheuniqueIDfortheclientwithinicecast,userandpassmaybeblank butcomefromtheHTTPbasicauththatthelistenerstates,ipisthelistenersIPaddressandagentistheUseragent fromthelistenersplayer. Themounthere(unlikethestart/endoptions)statestherequestedurlincludinganyqueryparameters,sofor instancetherequestedURLcanbe/stream.ogg&session=xyz,butnotethateachoptiondataisescapedbefore beingpassedviaPOST listener_remove ThisURLisforwhenalistenerconnectioncloses. POSTdetailsare action=listener_remove&server=myserver.com&port=8000&client=1&mount=/live&user=&pass=&duration=3 600

Againthisissimilartotheaddoption,thedifferencebeingthatadurationispassedreflectingthenumberof secondsthelistenerwasconnectedfor auth_header Theexpectedresponseheadertobereturnedthatallowstheauthencationtotakeplacemaybespecifiedhere.The defaultis icecastauthuser:1 butitcouldcananythingyoulike,forinstance HTTP200OK timelimit_header Listenerscouldhaveatimelimitimposedonthem,andifthisheaderissentbackwithafigure(whichrepresents seconds)thenthatishowlongtheclientwillremainconnectedfor. ANoteAboutPlayersAndAuthentication Wedonothaveanexaustivelistofplayersthatsupportlistenerauthentication.WeusestandardHTTPbasic authentication,andingeneral,manymediaplayerssupportthisiftheysupportanythingatall.Winampand Foobar2000 support HTTP basic authentication on windows, and XMMS supports it on unix platforms. Winamp/XMMSasleastsupportthepassingofqueryparameters,otherplayersmayalsodo

Win32SpecificDocumentation Thewin32portoficecast2issimplyaUIframeworkaroundthecoreicecast2server.Thewin32versionoficecast2 directlyusesthemainexecutableoficecast(staticallyincluded)andsimplyprovidesaGUIinterfacetoicecast2. Mostofthefeaturesoficecast2areavailableinthewin32port. ServerStatusTab Theserverstatustabcontainsinformationregardingstatisticsthatareglobaltotheserver.Therearetwotypesof statisticsinicecast2:sourcelevelandglobalstatistics.Globalstatisticsarecumulativestatsfromallsourcesoffered bytheserver.Sourcelevelstatisticsarestatswhichapplyonlytoasinglesourceattachedtotheserver. Examplesofglobalstatisticsare: Thenumberofcurrentsourcesconnected Thenumberofsourcesthathaveattemptedconnections Totalnumberofattemptedconnectionstotheserver TheServerStatustabcontainsataminimaltheglobalstatsfortheserver.Additionally,youmayaddsource specificstatstothistab.Theintentistoprovideasingle"dashboardview"ofwhat'sgoingonintheserver.Toadd sourcestatisticstotheServerStatustab,seethesectionontheStatstab. Addingstatstothewindowtitle. AnystatthatiscontainedontheServerStatustabcanbedisplayedastheicecast2windowtitle.Thisprovidesyet anothermechanismbywhichyoucanviewactivitiesontheserver.Toenablethisfeature,rightclickonanystatin theServerStatustab. RemovingsourcelevelstatsfromtheServerStatusTab. ToremoveasourcelevelstatthatyouhaveinsertedontotheServerStatusTab,simplerightclickthatstatisticand select"DeletefromGlobalStats".ThestatwillbedeletedfromtheServerStatustab,butwillstillremainonthe sourcelevelStatstab. EditingTheIcecastConfigFile Editingtheicecast2configurationfileisaverysimpleprocess.Foradescriptionofwhateachfieldmeans,seethe mainicecastdocumenation.Changestotheicecast2configurationcanonlybedonewhiletheserverisstopped.To editthecurrentserverconfigurationfile,select"Configuration/EditConfiguration"fromthemainmenu. StatsTab Thestatstabcontainsaviewofalltheconnectedmountpointsandthestatisticsthatgoalongwiththem.Each connectedmountpointisdisplayedintheleftpaneofthewindow,andallstatsfortheselectedmountpointare displayedintherightpaneofthewindow.

ServerStatusTab Overview Theserverstatustabcontainsinformationregardingstatisticsthatareglobaltotheserver.Therearetwotypesof statisticsinicecast2,sourcelevelandglobalstatistics.Globalstatisticsarethosethatareaccumilationsofstats fromallsourcesofferedbytheserver.Sourcelevelstatisticsarestatswhichapplyonlytoasinglesourceattached totheserver. Examplesofglobalstatisticsare: Thenumberofcurrentsourcesconnected Thenumberofsourcesthathaveattemptedconnections Totalnumberofattemptedconnectionstotheserver TheServerStatustabcontainsataminimaltheglobalstatsfortheserver.Additionally,youmayaddsource specificstatstothistab.Theintentistoprovideasingle"dashboardview"ofwhat'sgoingonintheserver. AddingStatsToTheWindowTitle AnystatthatiscontainedontheServerStatustabcanbedisplayedastheicecast2windowtitle.Thisprovidesyet anothermechanismbywhichyoucanviewactivitiesontheserver.Toenablethisfeature,rightclickonanystatin theServerStatustab. RemovingSourceLevelStatsFromTheServerStatusTab ToremoveasourcelevelstatthatyouhaveinsertedontotheServerStatusTab,simplerightclickthatstatisticand select"DeletefromGlobalStats".ThestatwillbedeletedfromtheServerStatustab,butwillstillremainonthe sourcelevelStatstab.

Glossary sourceclient Asourceclientisanexternalprogramwhichisresponsibleforsendingcontentdatatoicecast.Somesourceclients thatsupporticecast2areOddcast,ices2,ices0.3,andDarkIce. slaveserver(Relay) Theslaveserverinarelayconfigurationistheserverthatispullingthedatafromthemasterserver.Itactsasa listeningclienttothemasterserver. masterserver(Relay) Themasterserverinarelayconfigurationistheserverthathasthestreamthatisbeingrelayed. mountpoint Amountpointisaresourceontheicecastserverthatrepresentsasinglebroadcaststream.Mountpointsarenamed similar to files (/mystream.ogg, /mymp3stream). When listeners connect to icecast2, they must specify the mountpointintherequest(i.e.http://192.168.1.10:8000/mystream.ogg).Additionally,sourceclientsmustspecify a mountpoint when they connect as well. Statistics are kept track of by mountpoint. Mountpoints are a fundamentalaspectoficecast2andhowitisorganized. fallbackmountpoint A fallback mountpoint is configured with a parent mountpoint. In theevent of the parent mountpoint losing connectionwithicecast,Icecastwillthenmoveallclientscurrentlyconnectedtothenowdefunctmountpointto it'sfallbackmountpoint.

FrequentlyAskedQuestions GeneralQuestions WhatisIcecast? Icecast,theproject,isacollectionofprogramsandlibrariesforstreamingaudioovertheInternet.Thisincludes: Icecast,aprogramthatstreamsaudiodatatolisteners Libshout,alibraryforcommunicatingwithIcecastservers IceS,aprogramthatsendsaudiodatatoIcecastservers Asourceclientisanexternalprogramwhichisresponsibleforsendingcontentdatatoicecast.Somesourceclients thatsupporticecast2areOddcast,ices2,ices0.3,andDarkIce. Whatisicecast,theprogram? icecaststreamsaudiotolisteners,andiscompatiblewithNullsoft`sShoutcast. Whatislibshout? FromtheREADME: libshout is a library for communicating with and sending data to an icecast server. It handles the socket connection,thetimingofthedata,andpreventsbaddatafromgettingtotheicecastserver. WhatisIceS? IceSisaprogramthatsendsaudiodatatoanicecastservertobroadcasttoclients.IceScaneitherreadaudiodata fromdisk,suchasfromOggVorbisfiles,orsampleliveaudiofromasoundcardandencodeitonthefly. HowcanIviewthestreamstatuspage? Checkyouricecastconfigurationfileforanelementcalled<webroot>.Thisdirectorycontainswebstuff.Init, placeafilecalled"status.xsl"thattransformsanXMLfilecontainingstreamdataintoawebpage(eitherXHTML orHTML). TherearesampleXSLstylesheetsavailableinicecast/web/intheCVSdistributionoficecast. Inaddition,thewebdirectorycanholdmultiplestatustransforms,ifyoucan'tdecidewhichoneyouwant. WhatcanIusetolistentoanIcecaststream? WemaintainalistofIcecastcompatibleaudioplayersathttp://www.icecast.org/

Ezstream AboutEzstream Prerequisites Installation Usage ExternalDecoders/Encoders OperatingSystemSpecificNotes InformationAboutTheBinaryEzstreamDistributionForWindows EzstreamMetadataExampleXMLConfigurationFile EzstreamMp3ExampleXMLConfigurationFile EzstreamReencodeMp3ExampleXMLConfigurationFile EzstreamVorbisExampleXMLConfigurationFile EzstreamReencodeVorbisExampleXMLConfigurationFile EzstreamReencodeTheoraExampleXMLConfigurationFile EzstreamManPage

AboutEzstream EzstreamisacommandlinesourceclientforIcecastmediastreamingservers.Itbeganasthesuccessoroftheold "shout"utility,andhassincegainedalotofusefulfeatures. Initsbasicmodeofoperation,itstreamsmediafilesordatafromstandardinputwithoutreencodingandthus requiresonlyverylittleCPUresources.Itcanalsousevariousexternaldecodersandencoderstoreencodefrom oneformattoanother,andstreamtheresulttoanIcecastserver.Withreencodingenabled,ezstreamisavery flexiblesourceclient. Supported media formats for streaming are MP3, Ogg Vorbis and Ogg Theora. Ezstream natively supports metadatainMP3(ID3v1only)andOggVorbis,ormanymoreformatswhenitisbuiltwiththeTagLiboption. EzstreamisfreesoftwareandlicensedundertheGNUGeneralPublicLicense.

Prerequisites Ezstreamdependson: libshout2.2.x (http://www.icecast.org/) libxml2.x (http://xmlsoft.org/) Ezstreamoptionallyuses: ForreadingmetadatafromOggVorbisfiles: TagLib1.x(1.4ornewerrecommended,willbeusedviathelibtag_cwrapper) (http://developer.kde.org/~wheeler/taglib.html) OR: libvorbis1.x (http://www.vorbis.com) UsingTagLibisrecommended,asitallowsezstreamtoreadmetadatafrommanyadditionalmediafiletypes. ForbasicnonASCIIcharsetsupportinmetadataandfilenames: Libiconv,ificonv()isnotavailableinthesystemlibc. (http://www.gnu.org/software/libiconv/)

Installation TheezstreamsoftwareusestheGNUautotoolstoconfigure,buildandinstallonavarietyofsystems.Asidefrom thestandardautoconfoptionsoftheconfigurescript,acoupleofadditionaloptionsareavailable: enableexamplesdir=DIR exampleconfigurationfilesinstallationdirectory (default:DATADIR/examples/ezstream) enabledebugenablememorydebugging(default:no) withlibvorbis=PFXprefixwheretheVorbislibraryheaderfilesandlibraryareinstalled(default:autodetect) withlibvorbisincludes=DIR directorywhereVorbislibraryheaderfilesareinstalled(optional) withlibvorbislibs=DIR directorywheretheVorbislibrariesareinstalled (optional) withtaglib=PFXprefixwheretheTagLibheaderfilesandlibraryareinstalled(default:autodetect) withtaglibincludes=DIR directorywhereTagLibheaderfilesareinstalled (optional) withtagliblibs=DIRdirectorywhereTagLibisinstalled(optional) Thecompilationandinstallationprocessthenboilsdowntotheusual $./configurehelp|less#Skimovertheavailableoptions $./configure[options]&&make&&[sudo]makeinstall #Configure,buildandinstall #[asroot]thesoftware Ifthisprocedureisunfamiliartoyou,pleaseconsulttheINSTALLfileformoredetailedinstructions. Whentheconfigurationkeepsfailingdespitehavingalldependenciesinstalled,takenoteofthemoreverbose errormessagesinconfig.log.Ifnecessary,itispossibletodirectlycustomizemanybuildflagsthroughenvironment variables.Seethe"influentialenvironmentvariables"listinthehelpoutput.

Usage Once ezstream is successfully installed, type "man ezstream" (without quotes) on the command line for a comprehensivemanual.Thisdistributionpackagealsocomeswithexampleconfigurationfilesthatcanbeusedas aguidetoconfigureezstream. Notethatallbyitself,ezstreamisnotparticularlyuseful.ItrequiresarunningIcecastservertostreamto,which thenrelaysthestreamtomanylisteners.Ifthiscomesasasurprise,browsetohttp://www.icecast.org/foralot moreinformation,resources,andothersourceclients.

ExternalDecoders/Encoders Ezstreamshouldbeabletoworkwithanymediadecoderandencoderthatfulfillsthefollowingrequirements: 1.Itneedstobeexecutableonthecommandlineandnotrequireagraphicaldisplaytofunction. 2.1.AdecoderneedstobecapableofsendingRAWdatatostandardoutput. 2.2.AnencoderneedstobecapableofreadingRAWdatafromstandardinput. 2.3.Acombinedde/encoderneedstobecapableofsendingmediadatathatcanbestreamedtostandardoutput. Mediaformatsthatezstreamdoesnotsupportdirectlyarepassedthroughunaltered.Whethertheyworkornot dependsonthelevelofsupportofferedbytheversionoflibshoutezstreamislinkedwith. Thefollowingincompletelistofprogramsshowsafewthatareknowntowork. Thesearealsousedintheexampleconfigurationfiles: MP3 Decoder:madplay(http://mad.sf.net/) Encoder:lame(http://lame.sf.net/) OggVorbis: Decoder:oggdec Encoder:oggenc Bothutilitiesareinthevorbistoolspackage(http://www.vorbis.com/). FLAC: Decoder:flac(http://flac.sf.net/) Encoder:(None.Notsupportedbylibshoutatthetimeofwriting,andthuscannotbeusedbyezstream.) OggTheora: Decoder/Encoder:ffmpeg2theora(http://v2v.cc/~j/ffmpeg2theora/)

OperatingSystemSpecificNotes EzstreamandSunPROcc/c99onSolaris: EzstreammaynotbuildwithSunPROcc/c99"outofthebox"ifathreadedlibshoutwasbuiltwithgcc.Thisknown issueresultsinthefollowingerrormessagefromthelinker: ld:fatal:optionhandbuildingadynamicexecutableareincompatible ThisisrelatedtogccandGNUldusingdifferentcompiler/linkerflags,relatedtoPOSIXthreads,thantheSunPRO compilers.Thesearebeingpassedontoezstream,whereccorc99ultimatelychokesonthem. Ezstreamcompileswithbothcc/c99andgcciflibshoutwasbuiltwithSun'scompiler.Iflibshoutwasbuiltwith gcc,compileezstreamwithgccaswell.

InformationAboutTheBinaryEzstreamDistributionForWindows ZIPArchiveContents FileDescription \COPYING.txtLicenseforusing,modifyinganddistributingEzstream. \README.txtThisfile. \ezstream.1.pdfTheezstreammanualinPDFformat. \ezstream.exeTheezstreamexecutablefile. \ezstreamX.Y.Z.zipTheezstreamsourcedistribution,fromwhichezstream.exewasbuilt. \examples\*.xmlEzstreamexampleconfigurationfiles. \examples\*.shExampleplaylistandmetadatascripts,fordemonstrationalpurposes(theseareshellscripts.) Installation As of version 0.3.0, ezstream no longer comes with an installer. If you have a previous version of ezstream installed,youmightwanttosimplyuninstallit. Theezstream.exefilecanberunfromanylocation.Toinstallit,simplycopyittoalocationofyourchoosing.To makeitavailableanywhereonthesystem,addtheinstallationfoldertoyourPATHenvironmentvariable. Ifitdoesn'tstart,e.g.running >ezstream.exeh doesnotshowthecommandlinehelp,theMicrosoftVisualC++2008runtimelibrariesaremissing.Download andinstallvcredist_x86.exe,whichcanbeeasilyfoundonwww.microsoft.comvia http://www.google.com/search?q=vc+2008+redist LimitedFunctionality AfewusefulfeaturesaremissingintheWindowsversionofezstream: Runtimecontrolviasignalsisnotpossible. Someusefulexternalutilities(encoders,decoders)maynotbeavailableonWindows. SourceCode Ezstreamuses: zlib(http://www.zlib.net/,BSDlikelicense) libiconv(http://www.gnu.org/software/libiconv/,LGPL) libxml2(http://xmlsoft.org/,BSDlikelicense) libogg,libvorbis,libvorbisfile(http://www.vorbis.com/,BSDlikelicense) libFLAC(http://flac.sourceforge.net/,BSDlikelicense) libtheora(http://www.theora.org/,BSDlikelicense) libshout(http://www.icecast.org,LGPL) TagLib(http://ktown.kde.org/~wheeler/taglib.html,LGPL)

Theselibrariesarestaticallylinkedintotheezstream.exefile. EzstreamitselfislicensedundertheGPLversion2(seeCOPYING.txtfordetails.) Support For information on how to report issues with ezstream, please visit the ezstream home page at http://www.icecast.org/ezstream.php

EzstreamMetadataExampleXMLConfigurationFile <! EXAMPLE: Ogg Vorbis stream WITHOUT reencoding, using an external playlist program and an external metadataprogram,withacustomformatstring. Thisexamplestreams(only)OggVorbisfilesthatareprovidedbyanexternalplaylistscript.Thescriptmustnot returnfilenamesofnon.oggfiles.Metadataforthisstreamisnotacquiredfromthemediafileitselfbutfrom anotherexternalprogram'meta.sh'. > <ezstream> <url>http://localhost:8000/vorbis.ogg</url> <sourcepassword>hackme</sourcepassword> <format>VORBIS</format> <!Theplaylistprogramnameisprovidedhere:> <filename>play.sh</filename> <!Tellezstreamthat<filename/>isaplaylistprogram:> <playlist_program>1</playlist_program> <!Usethemeta.shscripttogetmetadata> <metadata_progname>meta.sh</metadata_progname> <!Setthemetadatastringaccordingtothisformat:> <metadata_format>@s@:@a@@t@</metadata_format> <! Thefollowingsettingsareusedtodescribeyourstreamtotheserver. It'suptoyoutomakesurethatthebitrate/quality/samplerate/channels informationmatchesupwithyourinputstreamfiles. > <svrinfoname>MyStream</svrinfoname> <svrinfourl>http://www.oddsock.org</svrinfourl> <svrinfogenre>RockNRoll</svrinfogenre> <svrinfodescription>Thisisastreamdescription</svrinfodescription> <svrinfobitrate>96</svrinfobitrate> <svrinfoquality>2.0</svrinfoquality> <svrinfochannels>2</svrinfochannels> <svrinfosamplerate>44100</svrinfosamplerate> <!AllowtheservertoadvertisethestreamonapublicYPdirectory:> <svrinfopublic>1</svrinfopublic> </ezstream>

EzstreamMp3ExampleXMLConfigurationFile <! EXAMPLE:MP3playliststreamWITHOUTreencoding ThisexamplestreamsaplaylistthatcontainsonlyMP3files.Nootherfileformatsmaybelisted.Sinceezstream will not be doing any reencoding, the resulting stream format (bitrate, samplerate, channels) will be of the respectiveinputfiles. > <ezstream> <url>http://localhost:8000/stream</url> <sourcepassword>hackme</sourcepassword> <format>MP3</format> <filename>playlist.m3u</filename> <!Oncedonestreamingplaylist.m3u,exit:> <stream_once>1</stream_once> <! Thefollowingsettingsareusedtodescribeyourstreamtotheserver. It'suptoyoutomakesurethatthe bitrate/samplerate/channelsinformationmatchesupwithyourinputstreamfiles.Notethat<svrinfoquality/> onlyappliestoOggVorbisstreams. > <svrinfoname>MyStream</svrinfoname> <svrinfourl>http://www.oddsock.org</svrinfourl> <svrinfogenre>RockNRoll</svrinfogenre> <svrinfodescription>Thisisastreamdescription</svrinfodescription> <svrinfobitrate>128</svrinfobitrate> <svrinfochannels>2</svrinfochannels> <svrinfosamplerate>44100</svrinfosamplerate> <! ProhibittheservertoadvertisethestreamonapublicYPdirectory: > <svrinfopublic>0</svrinfopublic> </ezstream>

EzstreamReencodeMp3ExampleXMLConfigurationFile <! EXAMPLE:MP3streamusinganexternalplaylistprogram,WITHreencoding ThisexamplestreamsaplaylistthatmaycontainMP3,OggVorbisandFLACfiles.Ezstreamwilluseexternal decoderstoreadthemediafiles,andreencodethemtoMP3usingthelameMP3encoder.Theoutputstream settingsarecontrolledviatheparamterstolame. > <ezstream> <url>http://localhost:8000/stream</url> <sourcepassword>hackme</sourcepassword> <! Sincethereencodingfeatureisenabledbelow,<format/>setstheoutputformatofthestream. > <format>MP3</format> <filename>playlist.pl</filename> <! Indicatethat<filename>containsanexecutableprogramorscript,whichprintsasinglelinewithafilename tostandardoutput: > <playlist_program>1</playlist_program> <! Thefollowingsettingsareusedtodescribeyourstreamtotheserver.It'suptoyoutomakesurethatthe bitrate/samplerate/channelsinformationmatchesupwithyourlameencodersettingsbelow. > <svrinfoname>MyStream</svrinfoname> <svrinfourl>http://www.oddsock.org</svrinfourl> <svrinfogenre>RockNRoll</svrinfogenre> <svrinfodescription>Thisisastreamdescription</svrinfodescription> <svrinfobitrate>128</svrinfobitrate> <svrinfochannels>2</svrinfochannels> <svrinfosamplerate>44100</svrinfosamplerate> <! ProhibittheservertoadvertisethestreamonapublicYPdirectory: > <svrinfopublic>0</svrinfopublic> <reencode> <!Enablethereencodingfeature:> <enable>1</enable> <! Each<encdec/>elementspecifiesapairofprogramstobeusedfordecodingandencoding,respectively, andwhichfileextensionandoutputstreamformattheyapplyto. Alltheconfigurationoftheoutputstreamisusuallydonebyusingtheappropriatecommandlineparameters oftheencodersinthe<encode/>elements. New<encdec/>sectionscanbeaddedfornewinput/outputformats. Distortedaudio,oraudioplayingatthewrongspeed/pitchmaybecausedbyconflictingsampleratesinthe various<decode/>and<encode/>sections,byteorder(endianness)issuesandmonoinputfiles.Seethe documentationonthevariousde/encodersfortheoptionsthatneedtobeusedtocreateaconsistentstreamof rawsamples. > <encdec>

<!SupportforFLACdecoding:> <format>FLAC</format> <match>.flac</match> <decode>flacsdforcerawformatsign=signedendian=littleo"@T@"</decode> <!<encode>NotsupportedYet</encode>> </encdec> <encdec> <! SupportforMP3decodingviamadplay,andencodingviaLAME: > <format>MP3</format> <match>.mp3</match> <!Note:madplayuseshostbyteorderforrawsamples.> <decode>madplayb16R44100Soraw:"@T@"</decode> <encode>lamepresetcbr128rs44.1bitwidth16</encode> </encdec> <encdec> <! SupportforVorbisdecodingviaoggdec,andencodingviaoggenc: > <format>VORBIS</format> <match>.ogg</match> <decode>oggdecRb16e0s1o"@T@"</decode> <encode>oggencrB16C2R44100rawendianness0q1.5t"@M@"</encode> </encdec> </reencode> </ezstream>

EzstreamVorbisExampleXMLConfigurationFile <! EXAMPLE:OggVorbisplayliststreamWITHOUTreencoding ThisexamplestreamsaplaylistthatcontainsonlyOggVorbisfiles.Nootherfileformatsmaybelisted.Since ezstreamwillnotbedoinganyreencoding,theresultingstreamformat(quality/bitrate,samplerate,channels)will beoftherespectiveinputfiles. > <ezstream> <url>http://localhost:8000/vorbis.ogg</url> <sourcepassword>hackme</sourcepassword> <format>VORBIS</format> <filename>playlist.m3u</filename> <!Fordemonstrationalpurposes,explicitlysetcontinuousstreaming:> <stream_once>0</stream_once> <! Thefollowingsettingsareusedtodescribeyourstreamtotheserver.It'suptoyoutomakesurethatthe bitrate/quality/samplerate/channelsinformationmatchesupwithyourinputstreamfiles. > <svrinfoname>MyStream</svrinfoname> <svrinfourl>http://www.oddsock.org</svrinfourl> <svrinfogenre>RockNRoll</svrinfogenre> <svrinfodescription>Thisisastreamdescription</svrinfodescription> <svrinfobitrate>96</svrinfobitrate> <svrinfoquality>2.0</svrinfoquality> <svrinfochannels>2</svrinfochannels> <svrinfosamplerate>44100</svrinfosamplerate> <!AllowtheservertoadvertisethestreamonapublicYPdirectory:> <svrinfopublic>1</svrinfopublic> </ezstream>

EzstreamReencodeVorbisExampleXMLConfigurationFile <! EXAMPLE:OggVorbisplayliststreamWITHreencodingandrandomplayback ThisexamplestreamsaplaylistthatmaycontainMP3,OggVorbisandFLACfiles.Ezstreamwilluseexternal decoderstoreadthemediafiles,andreencodethemtoOggVorbisusingtheoggencencoder.Theoutputstream settingsarecontrolledviatheparamterstooggenc. > <ezstream> <url>http://localhost:8000/vorbis.ogg</url> <sourcepassword>hackme</sourcepassword> <! Sincethereencodingfeatureisenabledbelow,<format/>setstheoutputformatofthestream. > <format>VORBIS</format> <filename>playlist.m3u</filename> <!Enableplaylistshuffling:> <shuffle>1</shuffle> <! Thefilein<filename>isaregularplaylistandnotaprogram.Fordemonstrationalpurposes,explicitlystate thishere: > <playlist_program>0</playlist_program> <! Thefollowingsettingsareusedtodescribeyourstreamtotheserver. It'suptoyoutomakesurethatthe bitrate/quality/samplerate/channelsinformationmatchesupwithyouroggencencodersettingsbelow. > <svrinfoname>MyStream</svrinfoname> <svrinfourl>http://www.oddsock.org</svrinfourl> <svrinfogenre>RockNRoll</svrinfogenre> <svrinfodescription>Thisisastreamdescription</svrinfodescription> <svrinfobitrate>88</svrinfobitrate> <svrinfoquality>1.5</svrinfoquality> <svrinfochannels>2</svrinfochannels> <svrinfosamplerate>44100</svrinfosamplerate> <!AllowtheservertoadvertisethestreamonapublicYPdirectory:> <svrinfopublic>1</svrinfopublic> <reencode> <!Enablethereencodingfeature:> <enable>1</enable> <! Each<encdec/>elementspecifiesapairofprogramstobeusedfordecodingandencoding,respectively, andwhichfileextensionandoutputstreamformattheyapplyto. Alltheconfigurationoftheoutputstreamisusuallydonebyusingtheappropriatecommandlineparameters oftheencodersinthe<encode/>elements. New<encdec/>sectionscanbeaddedfornewinput/outputformats. Distortedaudio,oraudioplayingatthewrongspeed/pitchmaybecausedbyconflictingsampleratesinthe various<decode/>and<encode/>sections,byteorder(endianness)issuesandmonoinputfiles.Seethe documentationonthevariousde/encodersfortheoptionsthatneedtobeusedtocreateaconsistentstreamof rawsamples. >

<encdec> <!SupportforFLACdecoding:> <format>FLAC</format> <match>.flac</match> <decode>flacsdforcerawformatsign=signedendian=littleo"@T@"</decode> <!<encode>NotsupportedYet</encode>> </encdec> <encdec> <! SupportforMP3decodingviamadplay,andencodingviaLAME: > <format>MP3</format> <match>.mp3</match> <!Note:madplayuseshostbyteorderforrawsamples.> <decode>madplayb16R44100Soraw:"@T@"</decode> <encode>lamepresetcbr128rs44.1bitwidth16</encode> </encdec> <encdec> <! SupportforVorbisdecodingviaoggdec,andencodingviaoggenc: > <format>VORBIS</format> <match>.ogg</match> <decode>oggdecRb16e0s1o"@T@"</decode> <encode>oggencrB16C2R44100rawendianness0q1.5t"@M@"</encode> </encdec> </reencode> </ezstream>

EzstreamReencodeTheoraExampleXMLConfigurationFile <! EXAMPLE:OggTheoraplayliststreamWITHreencodingandsequentialplayback Thisexamplestreamsaplaylistthatmaycontain.aviandMPEGfiles.Ezstreamwillusetheffmpeg2theora programtobothdecodeandreencodethevideofilestoOggTheora.Theoutputstreamsettingsarecontrolledvia theparamterstoffmpeg2theora. > <ezstream> <url>http://localhost:8000/theora.ogg</url> <sourcepassword>hackme</sourcepassword> <! Sincethereencodingfeatureisenabledbelow,<format/>setstheoutputformatofthestream. > <format>THEORA</format> <filename>playlist.m3u</filename> <! Playlistshufflingisdisabled,whenthe<shuffle/>elementdoesnotexistoriscommentedout: > <!<shuffle>1</shuffle>> <! Thefollowingsettingsareusedtodescribeyourstreamtotheserver. It'suptoyoutomakesurethatthe bitrate/quality/samplerate/channelsinformationmatchesupwithyouroggencencodersettingsbelow. > <svrinfoname>MyStream</svrinfoname> <svrinfourl>http://www.oddsock.org</svrinfourl> <svrinfogenre>Documentary</svrinfogenre> <svrinfodescription>Thisisastreamdescription</svrinfodescription> <svrinfobitrate>200</svrinfobitrate> <svrinfochannels>2</svrinfochannels> <svrinfosamplerate>44100</svrinfosamplerate> <! Amissingorcommentedout<svrinfopublic/>elementmeansnoadvertisingonYPforthisbroadcast: > <!<svrinfopublic>1</svrinfopublic>> <reencode> <!Enablethereencodingfeature:> <enable>1</enable> <! Each<encdec/>elementspecifiesapairofprogramstobeusedfordecodingandencoding,respectively, andwhichfileextensionandoutputstreamformattheyapplyto. Alltheconfigurationoftheoutputstreamisusuallydonebyusingtheappropriatecommandlineparameters oftheencodersinthe<encode/>elements. New<encdec/>sectionscanbeaddedfornewinput/outputformats. Distortedaudio,oraudioplayingatthewrongspeed/pitchmaybecausedbyconflictingsampleratesinthe various<decode/>and<encode/>sections,byteorder(endianness)issuesandmonoinputfiles.Seethe documentationonthevariousde/encodersfortheoptionsthatneedtobeusedtocreateaconsistentstreamof rawsamples. > <encdec> <!

 Support for THEORA. Ogg Theora streams are created differently with ffmpeg2theora, which does the completereencodingonitsown.Therefore,weonlysupplya<decode/>elementandletezstreampassthrough theresultingstreamunalteredtoIcecast. > <format>THEORA</format> <match>.avi</match> <decode>ffmpeg2theorax192y128a0v4title"@M@"o"@T@"</decode> </encdec> <encdec> <format>THEORA</format> <match>.mpg</match> <decode>ffmpeg2theorax192y128a0v4title"@M@"o"@T@"</decode> </encdec> </reencode> </ezstream>

EzstreamManPage NAME ezstreamsourceclientforIcecastwithexternalde/encodersupport SYNOPSIS ezstream[hnqVv]cconfigfile DESCRIPTION TheezstreamutilityisasourceclientfortheIcecastmediastreamingserver. Initsbasicmodeofoperation,it streamsmediafilesanddatafromstandardinput"asis"suchasOggVorbis,OggTheoraandMP3toa server. Itcanalsousevariousexternaldecodersandencoderstoreencodefromoneformattoanother,and streamtheresult.Theonlyrequirementisthattheexternalprogramssupportwritingtoorreadingfromstandard input,andcanbeusedfromthecommandline. Commandlineparameters cconfigfile UsetheXMLconfigurationinconfigfile.(Mandatory.) hPrintasummaryofavailablecommandlineparameterswithshortdescriptionsandexit. nNormalizemetadatastringsbyremovingexcesswhitespaces. qBemorequiet.Suppresstheoutputthatexternalprogramssendtostandarderror. VPrinttheezstreamversionnumberandexit. vProducemoreverboseoutputfromezstream.Usetwiceforevenmoreverboseoutput. Whentheqandvparametersareprovidedsimultaneously,anadditionallineofinformationaboutthecurrently streamedfileplaylistposition,approximateplayingtimeandbitrateisdisplayed. Runtimecontrol On POSIX systems, ezstream offers limited runtime control via signals. By sending a signal to the ezstream process,e.g.withthekill(1)utility,acertainactionwillbetriggered. SIGHUP Rereadstheplaylistfileafterthetrackthatiscurrentlystreamed. Iftheplaylistisnottobeshuffled,ezstream attempts to find the previously streamed file and continue with the one fol lowing it, or restarts from the beginningofthelistotherwise. SIGUSR1 Skipsthecurrentlyplayingtrackandmovesontothenextinplaylistmode,orrestartsthecurrenttrackwhen streamingasinglefile. SIGUSR2 Triggers rereading of metadata for the stream by running the program or script specified in <metadata_progname/>(seebelow.)Thisistheonlymeaningfulsignalwhenstreamingfromstandardinput.

TheezstreamutilityusesasimpleXMLconfigurationfileformat. Ithasatreelikestructureandismadeupof XMLelements.OfallthepossibleXMLfeatures,onlyregularelementsthatcontaintextorotherelements,and comments,appearinanezstreamconfigurationfile. Eachelementintheconfigurationfileconsistsofastarttag,itscontentandanendtag.Forexample: <filename>playlist.m3u</filename> <!XMLcommentslooklikethis.> Inthissection,eachavailableelementislistedanddescribed.Notethatforthispurpose,elementsareintroduced intheirshort,i.e.emptyform.Intheconfigurationfile,theyneedtobeusedasstarttag+content+endtag,like intheintroductoryexampleshownabove. Rootelement <ezstream/> (Mandatory.)Theconfigurationfilesrootelement.Itcontainsallotherconfigurationelements. Globalconfigurationelements Eachoftheglobalconfigurationelementshavethe<ezstream/>elementastheirparent. <url/> (Mandatory.)SpecifiesthelocationandmountpointoftheIcecastserver,towhichthestreamwillbesent.The contentmustbeoftheformhttp://server:port/mountpointForexample: <url>http://example.com:8000/stream.ogg</url> <sourcepassword/> (Mandatory.)SetsthesourcepasswordforauthenticationwiththeIcecastserver. <format/> (Mandatory.)Thiselementhastwodifferentmeanings,dependingonwhetherreencodingisenabledornot.It specifiestheoutputformatofthestreamifreencodingisenabled.Otherwise,itspecifiestheinputformatofall inputfiles.RecognizedandsupportedvaluesforoutputstreamformatsareVORBIS,MP3andTHEORA.Other valueswillbeignoredandcauseezstreamtosimplypassthroughthedata,whichmayormaynotwork. <filename/> (Mandatory.)Setthepathandnameofasinglemediafile,aplaylist,thenameofanexternalprogram(see below),orthekey wordstdinforstreamingfromstandardinput. Playlistsarerecog nizedbytheirfilename extensionandendwitheither.m3uor.txt. Aplaylistconsistsoffilenames,oneentryperline. Commentsinplaylistsareintroducedbya#signatthe beginningofalineandignoredbyezstream. <playlist_program/> (Optional.)Setto1(one)toindicatethatthefilein<filename/>isactuallyanexecutableprogramorscript.If setto0(zero),<filename/>contentisassumedtobeamediafile,playlistfileorthekeywordstdin(thedefault). SeetheSCRIPTINGsectionfordetailsonhowtheplaylistprogrammustbehave. <shuffle/> (Optional.)Setto1(one)torandomlyshuffletheentriesoftheplaylistspecifiedin<filename/>. Filesare playedsequentiallyifsetto0(zero)orwhenthe<shuffle/>elementisabsent. Thisoptionwillbeignoredif <playlist_program/>issetto1(one.) <metadata_progname/> (Optional.)Setthepathandnameofanexecutableprogramorscriptthatshouldbeusedbyezstreamtosetthe

metadataofthestream. Theprogramisautomaticallyqueriedwhenanewtrackisstreamed,orwhenevertheSIGUSR2signalisreceived. Ifthe<metadata_progname/>elementispresentintheconfiguration,noattemptswillbemadetoreadmetadata fromfilesthatarebeingstreamed.Ifthisbehaviorisnotdesired,itshouldberemovedorcommentedoutin theconfigurationfile. SeetheSCRIPTINGsectionfordetailsonhowthemetadataprogrammustbehave. <metadata_format/> (Optional.)Settheformatofthestringthatshouldbeusedforthe@M@placeholderwhensettingmetadata withanexternalprogramorscriptvia<metadata_progname/>. SeetheMETADATAsectionfordetailsonhowmetadataishandledbyezstream. <stream_once/> Setto1(one)inordertostreamthecontentof<filename/>onlyonce,andto0(zero)forcontinuousstreaming (thedefault). <reconnect_tries/> SethowmanyattemptsshouldbemadetoreconnecttotheIcecastserverincasetheconnectionisinterrupted. Thedefaultistotryindefinitely,whichisequaltosettingthisconfigurationoptionto0(zero). <svrinfoname/> (Optional.)Setthenameofthebroadcast.Informationalonly. <svrinfourl/> (Optional.)SettheURLofthewebsiteassociatedwiththebroadcast.Informationalonly. <svrinfogenre/> (Optional.)Setthegenreofthebroadcast.Informationalonly,usedforYP . <svrinfodescription/> (Optional.)Setthedescriptionofthebroadcast.Informationalonly,usedforYP . <svrinfobitrate/> (Optional.)Setthebitrateofthebroadcast.ThissettingisalsopurelyinformationalandonlyusedforYP .The valueissetbytheuserandnotezstream,andshouldmatchthebitrateofthestream. <svrinfoquality/> (Optional.)SetthequalitysettingofanOggVorbisbroadcast.Informationalonlyandneedstobesetbytheuser, usedforYP . <svrinfochannels/> (Optional.) Set the number of audio channels in the broadcast, e.g. 1 (one) for mono or 2 for stereo. Informationalonlyandneedstobesetbytheuser,usedforYP . <svrinfosamplerate/> (Optional.)Setthesamplerateofthebroadcast.Informationalonlyandneedstobesetbytheuser,usedforYP . <svrinfopublic/> (Optional.)Setto1(one)ifthebroadcastmaybelistedinapublicYPdirectory.Ifsetto0(zero),theIcecast serverwillnotsubmitthisstreamtoaYPdirectory,whichisalsothedefaultifthe<svrinfopublic/>elementis absent.

<reencode/> (Optional.)Elementthatcontainschildelements,whichspecifyifandhowreencodingshouldbedone. Reencodingsettings Eachofthereencodingconfigurationelementshavethe<reencode/>elementastheirparent. <enable/> Setto1(one)toenablereencoding.Ifsetto0(zero),noreencodingwillbedone,whichisalsothedefaultif the<enable/>elementisabsent. <encdec/> Elementthatcontainschildelements,whichspecifyhowtodecodeandencodeacertainmediafileformatfor streaming.Eachformatisdescribedbyaseparate<encdec/>element. Decoder/Encodersettings Eachofthedecoder/encoderconfigurationelementshavethe<encdec/>elementastheirparent. <format/> Thiselementisusedbyezstreamtofindtheappropriateencoderfortheoutputstreamformatspecifiedinthe <format/> element inside the global configuration. For consistency reasons, it is recom mended that this elementisalwayssupplied,evenforcurrentlyunsupportedoutputformats,withcontentsuchasVORBIS,MP3, THEORA,FLAC,etcetera. <match/> Set the filename extension used to identify a given media file for mat. This allows ezstream to find the appropriatedecoderforagivenfile.Shouldbesetto.mp3forMP3,.flacforFLAC,.oggforOggVorbis,andsoon. <decode/> Setthecommandtodecodethespecifiedmediafileformattorawdataandsendittostandardoutput.During runtime,theplaceholder@T@isreplacedwiththenameofthemediafile,asitisspecifiedinthe<filename/> elementorcontainedinaplaylistfile.Itshouldalwaysbeenclosedinquotes,topreventproblemswithfilenames thatcontainwhitespaces. Metadataplaceholderscanbeusedinthe<decode/>elementaswell,forcombinedde/encoderprogramsthat produce data that can be streamed. See the METADATA section for details on how metadata is handled by ezstream. Forexample,todecodeOggVorbisfilesusingtheoggdecutility: <decode>oggdecRo"@T@"</decode> <encode/> Setthecommandtoencoderawdata,receivedfromstandardinput,tothespecifiedstreamformat. Metadataplaceholderscanbeusedinthe<encode/>element.Fordetailsaboutusingmetadatainezstream,see belowintheMETADATAsection. Forexample,toencodeanOggVorbisstreamusingthequalitysetting1.5withtheoggencutility: <encode>oggencrq1.5t"@M@"</encode> SCRIPTING Theezstreamutilityprovideshooksforexternallycontrolledplaylistandmetadatamanagement.Thisisdoneby runningexternalprogramsorscriptsthatneedtobehaveinwaysexplainedhere.

CommonRules Theprogrammustbeanexecutablefile. Theprogrammustwriteonelinetostandardoutputandexit. Theprogrammustnotrequirearbitrarycommandlineoptionstofunction.Awrapperscriptmustbeusedif thereisnootherway. PlaylistPrograms Theprogrammustreturnonlyfilenames,withonefilenameperexecution. Theprogramshouldnotreturnanemptylineunlessezstreamissupposedtoknowthattheendoftheplaylist hasbeenreached.Thisissignificantwhenthe<stream_once/>optionisenabled. MetadataPrograms Theprogrammustnotreturnanything(justanewlinecharacterisokay)ifitiscalledbyezstreamwitha commandlineparameterthattheprogramdoesnotsupport. Whencalledwithoutcommandlineparameters,theprogramshouldreturnacompletestringthatshouldbe usedformetadata. Whencalledwiththecommandlineparameter"artist",theprogramshouldreturnonlytheartistinformationof themetadata.(Optional.) Whencalledwiththecommandlineparameter"title",theprogramshouldreturnonlythetitleinformationof themetadata.(Optional.) ThesuppliedmetadatamustbeencodedinUTF8. METADATA Themaintoolforhandlingmetadatawithezstreamisplaceholdersindecoderandencodercommandsthatare replacedwithrealcontentduringruntime. Thetrickypartisthatoneoftheplaceholdershastobehan dled differently,dependingonwherethemetadatacomesfrom.Thissectionwillexplaineachpossiblescenario. MetadataPlaceholders @T@Replacedwiththemediafilename.Requiredin<decode/>andisavailablein<metadata_format/>. @M@ Replacedwithametadatastring. Seebelowforadetailedexplana tion. Availablein<decode/>and <encode/>. @a@Replacedwiththeartistinformation.Availablein<decode/>,<encode/>and<metadata_format/>. @t@Replacedwiththetitleinformation.Availablein<decode/>,<encode/>and<metadata_format/>. @s@ Replacedwiththestringreturnedby<metadata_progname/>whencalledwithoutanycommandline parameters.Availableonlyin<metadata_format/>. The@M@Placeholder Whileallotherplaceholdersaresimplyreplacedwithwhateverdatatheyareassociatedwith,@M@iscontext sensitive.Thelogicusedbyezstreamisthefollowing: If(@M@ispresent) If(<metadata_progname/>AND<metadata_format/>) Replacewithformatstringresult. Else If(NOT<metadata_progname/>AND@t@ispresent) Replacewithemptystring. else Replacewithgeneratedmetadatastring. Endif Endif

Endif Thegeneratedmetadatastringfor@M@isoftheformatArtistTitle,ifbothartistandtitleinformationis available.Ifoneofthetwoismissing,theavailableoneisdisplayedwithoutaleadingortrailingdash,e.g.just Artist. Ifneitherartistnortitleareavailable,thenameofthemediafilewithoutitsfileextensionis used. MetadataCaveats Itispossibletogeneratestrangeresultswithoddcombinationsofplaceholders,externalmetadataprogramsand updatesduringruntimeviaSIGUSR2.Ifthingsstarttobecomejustconfusing,simplify. Metadataupdatesduringruntimearedonewitharelativelybrokenfeatureoflibshout. Additionalmetadata informationthatisalreadypresentinthestreamsentviaezstreamisusuallydestroyedandreplacedwiththe newdata.Itisnotpossibletoproperlydiscernbetweenartistandtitleinformation,whichmeansthatanything setwiththeSIGUSR2featurewillcontinuetoendupentirelyinthe"Title"fieldofastream. OfallpossibleOggbasedstreams,onlyOggVorbiscanhaveitsmetadatamanipulatedbyIcecast.Anyattemptof ezstreamtoupdateotherOggmetadataisactuallyanoop. WhileezstreamtriestodoitsbestwithrelayingmetadataaccuratelytoIcecast,andsubsequentlythelisteners, different codesets and locales can pose a problem. Especially when streaming MP3 files, it may help to explicitlysetacodesettoworkwithviatheLC_CTYPEenvironmentvariable,asezstreamassumesID3v1tagsto beintheuserscurrentlocale.Notethat,eventhoughsupportfordifferentlocalesisprovidedbyezstream,Icecast itselfand thelisteningclientsalsohaveasayinthematter. Theonlyway toensure consistentresultswith metadatainnonOggstreamsistousethecharactersavailableintheISO88591codeset. Externalencodersmayputadditional,andpossiblyartificial,restrictionsonvalidcharactersinmetadata. FILES /usr/share/examples/ezstream Directorycontainingexampleconfigurationfilesforvarioususesofezstream, aswellasexampleplaylistand metadatascripts. AUTHORS ezstreamwaswrittenby: EdZaleskioddsock@oddsock.org MoritzGrimmmdgrimm@gmx.net ThismanualwaswrittenbyMoritzGrimm.

IceS

IceSv2.0.1 IceS.04isasourceclientforbroadcastinginOggVorbisformattoanicecast2server Introduction BasicSetup ConfigFile AvailableInputModules FrequentlyAskedQuestions

Introduction

WhatIsIceS? IceS is a source client for a streaming server. The purpose of this client is to provide an audio stream to a streamingserversuchthatoneormorelistenerscanaccessthestream.Withthislayout,thissourceclientcanbe situatedremotelyfromtheicecastserver. TheprimaryexampleofastreamingserverusedisIcecast2,althoughotherscouldbeusedifcertainconditions aremet. WhatPlatformsAreSupported? CurrentlythefollowingUnixplatformsaresupported: Linux(MostflavorsincludingRedhatandDebian) FreeBSD OpenBSD Solaris WhereDoIGoForQuestions? IceSisdevelopedandmaintainedbythesamepeopleinvolvedwithIcecast2.Thereareseveralwaystocontact thedevelopmentteam BestWays Icecastmailinglisthttp://www.xiph.org/archives IcecastDevelopersmailinglisthttp://www.xiph.org/archives IcecastIRCchatroomirc.freenode.net:#icecast AlternateWays team@icecast.org

BasicSetup WhatDoesIceSRequire? IceSv2isnotagraphicalapplication,it'spurposeistostreamwhateveritisgivenintoastreamforfeedingtothe Icecaststreamingserver.Itdoeshoweverrequirethefollowing: liboggavailableathttp://www.vorbis.com libvorbisavailableathttp://www.vorbis.com libxml2availableatxmlsoft libshout2availableatTheIcecastsite Pleasenotethatinmanycases,prebuiltpackagesaresplitintotwo,aruntimepackage,typicallyconsistingofthe actualruntimelibraryandadevelopmentpackage,consistingofthesupportfilesneededtocompileandlinkthe application. Thefollowingareoptional ALSA.driverandlibsavailableatTheALSAsite WhatDoesIceSDo? IceSreadsaudiodatafromaninputandsendstheaudiodatatooneormorefilesoricecastservers.Beforeit's actuallysentout,someprocessingmaybeperformed,typicallyresamplingand/ordownmixingtoproducestreams suitedtovariousbandwidthrequirements. ThestreamsproducedareOggVorbisstreamssowhileicecast2iscapableofstreamingthesestreams,other streamingserversmaynotbe. WhatInputCanIceSHandle? Severalinputscurrentlyexist,butsomemaybedependantoncertainplatformsorifcertaindriversorlibrariesare available. OSSOpenSoundSystem.Typicallyusedonlinuxbasedsystemstogetliveinputfromasoundcard. ALSAAdvancedLinuxSoundArchitecture.LikeOSSbutwithvariousimprovementsforlinuxbasedsystems. stdinpcmUsesstandardinputtoreceivePCMaudio. playlistUsesaplaylisttoreadaudiofilesforprocessing. sunlikeOSS,butforSunSolaris,alsoworksforOpenBSD HowDoYouStartIceS? TheconfigurationofIceSisdoneviaanXMLbasedconfigfile.Whichyousupplyasanargumenttotheprogram atinvocationtime.Forexample ices/etc/ices.xml

ConfigFile Theices2configurationfileisinXMLformat,whichisdescribedindetailbelow.TherearesomesampleXMLfiles providedinthedistributionundertheconfdirectorywhichshowthemainwayicesisused. liveaudiostreaming,takesaudiofromthesoundcardwhichcanbecapturedfromsaytheMic,lineIn,CDora combinationofthese. icesoss.xml icesalsa.xml Playlistaudiostreaming,takespreencodedOggVorbisfilesandeithersendsthemasisorreencodesthemto differentsettings icesplaylist.xml GeneralLayout <?xmlversion="1.0"?> <ices> generalsettings streamsection </ices> GeneralSettings TheseapplytoIceSasawhole.Theexamplebelowgivesausefulexampletoworkto <background>0</background> <logpath>/var/log/ices</logpath> <logfile>ices.log</logfile> <logsize>2048</logsize> <loglevel>3</loglevel> <consolelog>0</consolelog> <pidfile>/var/log/ices/ices.pid</pidfile> background Setto1ifyouwantIceStoputitselfintothebackground. logpath AdirectorythatcanbewrittentobytheuserthatIceSrunsas.Thiscanbeanywhereyouwantbutaslogfilesare created,writeaccesstothestatedmustbegiven. logfile Thenameofthelogfilecreated.Onlogreopeningtheexistinglogfileisrenamedto<logfile>.1 logsize Whenthelogfilereachesthissize(inkilobytes)thenthelogfilewillbecycled(thedefaultis2Meg)

loglevel Anumberthatrepresentstheamountofloggingperformed. 1Onlyerrormessagesarelogged 2Theaboveandwarningmessagesarelogged 3Theaboveandinformationmessagesarelogged 4Theaboveanddebugmessagesarelogged consolelog Avalueof1willcausethelogmessagestoappearontheconsoleinsteadofthelogfiles.Settingthisto1is generally discouraged aslogsarecycledand writingto screen can cause stallsin theapplication,which is a problemfortimingcriticalapplications. pidfile Stateafilenamewithpathtobecreatedatstarttime.Thisfilewillthencontainasinglenumberwhichrepresents theprocessidoftherunningIceS.Thisprocessidcanthenbeusedtosignaltheapplicationofcertainevents. StreamSection Thisdescribeshowtheinputandoutgoingstreamsareconfigured. <stream> Metadata Input Instance </stream> Metadata <metadata> <name>MyStream</name> <genre>Rock</genre> <description>Ashortdescriptionofyourstream</description> <url>http://mysite.org</url> </metadata> Thissectiondescribeswhatmetadatainformationispassedintheheadersatconnectiontimetoicecast.This appliestoeachinstancedefinedwithinthestreamsectionbutmaybeoverriddenbyaperinstance<metadata> section. Input ThissectiondealswithgettingtheaudiodataintoIceS.Thereareafewwaysthatcanhappen.Typicallyit'seither fromaplaylistorviaasoundcard. Thelayoutisconsistentbetweenthedifferentinputmodules.Withintheinputsectionamoduletagisneededto identifythemoduleinquestion.Therestaremadeupofparamtagsspecifictothemodule.Therecanbeseveral paramtagssuppliedtoamodule.Detailsofthemoduleparametersareshownlater. Instance Multipleinstancescanbedefinedtoallowformultipleencodings,thisisusefulforencodingthesameinputto

multiple bitrates. Each instance defines a particular set actions that occur on the passed in audio. Any modificationstotheinputdataisisolatedtotheinstance. <instance> hostname port password mount yp resample downmix savefile encode </instance> hostname Statethehostnameoftheicecasttocontact,thiscanbeanameorIPaddressandcanbeipv4oripv6onsystems thatsupportIPv6.Thedefaultislocalhost. port Statetheporttoconnectto,thiswillbetheporticecastislisteningon,typically8000butcanbeany. password Forprovidingastream,ausername/passwordhastobeprovided,andmustmatchwhaticecastexpects. mount Mountpointsareusedtoidentifyaparticularstreamonaicecastserver,theymustbeginwith/andforthesakeof certainlisteningclientsshouldendwiththe.oggextension. yp BydefaultstreamswillnotbeadvertisedonaYPserverunlessthisisset,andonlytheniftheicecastifconfigured totalktoYPservers. Resample <resample> <inrate>44100</inrate> <outrate>22050</outrate> </resample> Whenencodingorreencoding,thereisapointwhereyoutakePCMaudioandencodetoOggVorbis.Insome situationsaparticularencodedstreammayrequirealowersampleratetoachievealowerbitrate.Theresample willmodifiytheaudiodatabeforeitenterstheencoder,butdoesnotaffectotherinstances. Themostcommonvaluesusedare48000,44100,22050and11025,andisreallyonlyusedtoresampletoalower samplerate,goingtoahigherrateservesnopurposewithinIceS. Downmix <downmix>1</downmix>

Somestreamswanttoreducethebitratefurther,reducingthenumberofchannelsusedtojust1.Converting stereotomonoisfairlycommonandwhenthisissetto1thenumberofchannelsencodedisjust1.Likeresample, thisonlyaffectstheoneinstanceit'senabledin. Savefile <savefile>/home/ices/dump/stream1.ogg</savefile> Sometimesthestreamtransmittedwantstobesavedtodisk.Thiscanbeusefulforliverecordings. encode <encode> <quality>0</quality> <nominalbitrate>65536</nominalbitrate> <maximumbitrate>131072</maximumbitrate> <minimumbitrate>1</minimumbitrate> <managed>0</managed> <samplerate>22050</samplerate> <channels>1</channels> <flushsamples>11000</flushsamples> </encode> quality Stateaqualitymeasurefortheencoder.Therangegoesfrom1to10where1isthelowestbitrateselection (default3),anddecimalscanalsobestated,soforexample1.5isvalid.Theactualbitrateusedwilldependonthe tuninginthevorbislibs,thesamplerate,channelsandtheaudiotoencode.Aqualityof0at44100hzand2 channelsistypicallyaroundthe64kbpsmark. nominalbitrate Stateabitratethattheencodershouldtrytokeepto.Thiscanbeusedasanalternativetoselectingquality. managed State1toenablefullbitratemanagementintheencoder.Thisisusedwithnominalbitrate,maximumbitrateand minimumbitratetoproduceastreamwithmorestrictbitraterequirements.Enablingthiscurrentlyleadstohigher CPUusage. maximumbitrate Statebitrateinbitspersecondtolimitmaxbandwidthusedonastream.Onlyappliesifmanagedisenabled. minimumbitrate Statebitrateinbitspersecondtolimitminimumbandwidthusedonastream.Onlyappliesifmanagedisenabled, thisoptionhasverylittleusesoshouldnotreallybeneeded. samplerate State the samplerate used for the encoding, this should be either the same as the input or the result of the resample.Gettingthesampleratewrongwillcausetheaudiotoberepresentedwrongandthereforesoundlikeit's runningtoofastortooslow. channels

Statethenumberofchannelstouseintheencoding.Thiswilleitherbethenumberofchannelsfromtheinputor 1ifdownmixisenabled. flushsamples ThisisthetriggerlevelatwhichOggpagesarecreatedforsendingtotheserver.Dependingonthebitrateand compressionachievedasingleoggpagecancontainmanysecondsofaudiowhichmaynotbewantedasthatcan triggertimeouts. Settingthistothesamevalueastheencodesampleratewillmeanthatapagepersecondissent,ifavaluethatis halfoftheencodedsamplerateisspecifiedthen2oggpagespersecondaresent.

AvailableInputModules Severalinputmodulesareavailable,dependingontheplatform,driversandlibrariesavailable.Thegenerallayout isdefinedas <input> <module>modulename</module> <paramname="name1">value</param> <paramname="name2">value</param> </input> Forliveinputyoumaywanttolookintovariousresourcesonthewebforinformationonsoundinput.Youmay findthatALSAforinstancesupportsaparticularsoundcardbetterthantheOpenSoundSystem. OpenSound <module>oss</module> <paramname="rate">44100</param> <paramname="channels">2</param> <paramname="device">/dev/dsp</param> <paramname="metadata">1</param> <paramname="metadatafilename">/home/ices/metadata</param> ThismoduleisforreadingliveinputfromtheOpenSoundSystemdrivers,oftenfoundonlinuxsystemsbutare availableonothers.ThiswillreadaudiofromtheDSPdeviceinaformatspecifiedintheparametersprovided. Thefollowingcanbeusedtoconfigurethemodule rate Thevalueisinhertz,44100isthesamplerateusedonCD's,butsomedriversmayprefer48000(DAT)oryoumay wanttousesomethinglower. channels Thenumberofchannelstorecord.Thisistypically2forstereoor1formono device Thedevicetoreadtheaudiosamplesfrom,it'stypically/dev/dspbuttheremaybemorethanonecardinstalled. metadata Checkformetadataarriving,ifanyarepresentthenthedataismarkedforanupdate.Themetadataisintheform oftag=value,andwhileOggVorbiscanhandleanysuppliedtags,mostplayerswillonlydoanythingwithartist andtitle. metadatafilename Thenameofthefiletoopenandreadthemetadatatagsfrom,withthisparametermissingstandardinputisread. Usingafileisoftenthebetterapproach.Whenusingthefileaccesstheprocedureisusuallytopopulatethefile contentsthensendaSIGUSR1totheIceSprocess. Theformatofthefileitselfisasimpleonecommentperlineformat,belowisatrivialexampleofthefile,other

tagscanbeusedbutplayerstendtoonlylookforartistandtitlefordisplaying.ThedatamustbeinUTF8(thisis notcheckedbyices,however). artist=Queen title=WeWillRockYou ALSA TheAdvancedLinuxSoundArchitecture(ALSA)isacompletelydifferentsoundsystemonlinuxbutprovidesOSS compatabilitysotheOSSdrivershouldworkwithitaswell.TouseALSAnativelyaseparatemoduleisused <module>alsa</module> <paramname="rate">44100</param> <paramname="channels">2</param> <paramname="device">hw:0,0</param> <paramname="periods">2</param> <paramname="buffertime">500</param> <paramname="metadata">1</param> <paramname="metadatafilename">/home/ices/metadata</param> TheparameterstoALSAaremostlythesameforOSS,asitperformsthesametask,iecapturesaudiofromtheDSP . device ThisisthedevicenameasusedinALSA.Thiscanbeaphysicaldeviceasinthecaseof"hw:0,0"oravirtualdevice likeonewithdsnoop. periods Thisspecifieshowmanyinterruptswillbegenerated(default:2) buffertime ThesizeofthebuffermeasuredinmS(default500) Sun TheSunSolarisDSPinputissimilarto OSS.ItallowsforreadingfromasoundcardonaSunSolarisUNIX. OpenBSDalsohasasounddriverthatissimilartosolarisandassuchshouldbeabletousethismodule. <module>sun</module> TheparametersarethesameastheOSSandALSAmodules. StdinPCM <module>stdinpcm</module> <paramname="rate">44100</param> <paramname="channels">2</param> <paramname="metadata">1</param> <paramname="metadatafilename">/home/ices/metadata</param> Thismoduleshouldalwaysbeavailable,andasyoucanseetheparametersarealmostthesameexceptforthe

device.ThePCMaudiocomesfromthestandardinputsoitcanbegeneratedfromsomeexternalappfeedinginto apipe. Asit'srawPCMbeingfedin,it'simpossibletodeterminethesamplerateandchannelssomakesurethestated parametersmatchtheincomingPCMortheaudiowillbeencodedwrongly. Playlist TheplaylistmoduleisusedtogetaudiofromsomepreencodedOggVorbisfiles.IceScurrentlycheckstoseeifthe samefilegetsplayedinsuccessionandskipsit,thismeansthathavingaplaylistrepeatwithonlyoneoggfile listedwon'twork.Themethodoffileselectionisdeterminedbytheplaylisttype.Thecurrenttypesarebasicand script. Basic <paramname="type">basic</param> <paramname="file">/path/to/playlist</param> <paramname="random">0</param> <paramname="once">0</param> <paramname="restartafterreread">1</param> file StateapathtoafilewhichwillcontainalistofOggVorbisfilenamestoplay.Oneperlinewithlinesbeginning with'#'beingtreatedascomments.Ifalinehasasingle''thenstandardinputisread,whichprovidesawayof gettingsomeexternalOggVorbisstreamintoices. random Whensetto1,theplaylistwillberandomisedwhentheplaylistisloaded.Bydefaultrandomisoff once Whensetto1,theplaylistisgonethroughonceandthenends,thiswillcauseicestoexit.Bydefaultonceisoff. restartafterreread Iftheplaylistisrereadmidwaythrough,whichmayoccuriftheplaylistwasupdatedthenthiswillrestartatthe beginningoftheplaylist.Bydefaultit'soff. Script <paramname="type">script</param> <paramname="program">/path/to/program</param> Program Stateapathtoaprogramwhichwhenrunwillwritetoit'sstandardoutputapathtoanOggVorbisfile.The programcanbeanythingfromanexecutabletoashellscriptaslongasitstarts,writesthefilenametoit'sstandard outputandthenexits.

FrequentlyAskedQuestions Thisforthosequestionspeoplehaveaskedasitwasn'tcoveredinthedocumentation Canicesplaymp3files? No,therehasn'tbeenmuchinterestinhandlingMP3withices2.Theolderversionices0.xmaybeofinterestin suchcases.IfyoureallywanttoencodetheVorbisstreamfromnonvorbisfilesthenyoucanplaythemwithan externalapplication,egxmms,anduseices2tocapturefromthesoundcard,butbeawarethatanyconversion fromonelossyformattoanotherisbadsomakesuretheoriginalmaterialishighquality. HowdoIencodefromLineIn? IceSwillreadfromtheDSPonthesoundcard,butwherethatgetstheaudiofromdependsonthemixersettings. Useautilitylikeaumix/alsamixertoseethesettingsandchangethecaptureorrecordingdevice.Usuallythe defaultistheMic WhenIstartices2itseemstogetstucknotdoinganything? Ifyouareusingliveinput,checktoseeifsomethingelseisholdingtherecordingdevice(typically/dev/dsp)open. Agoodcandidateisesd.Whathappensisthatthedriveronlyallowsoneapplicationtohavethedeviceopenat anyonetime,asecondattemptwilljustblock. Some OSSdrivers allowmultiple opensbuton ALSAyoucanconfigure a virtual device inasound.conf, type dsnoop/dmix,whichallowsaccessformultipleapps. Icesreportsamessageaboutfailingtosetsamplerateonliveinput? Somehardware/driversarelimitedinthesettingstheysupport.Sometimestheyonlysupportonesampleratelike 48khz.Youhavetoexperimentifthedocumentationforthedeviceisnotspecific. CanIdocrossfadingwiththeplaylist? Icesdoesnotdomuchinthewaymanipulatingtheaudioitself,resamplinganddownmixingareavailableasthat hasadirecteffectonencodinganoutgoingstream.Icescanstillbeusedinconjunctionwithotherapplications suchasxmmsbymakingicesreadfromthesaythedsp(egoss,alsaetc),thatwayanythingthatisplayedbythat otherapplicationisencodedandsenttoicecast. MyplayerconnectsbutIdon'thearanything? Ifyouaregettingdatathroughtotheplayerandthesettingsshowlikethesamplerateandchnnelsthenitis probablythemixersettingswhicharesetincorrectlyandicescanonlyreadsilence.Acommonexample,ALSA mayhavemanylevelsinthemixerandbydefaulttheyareallmuted. Myplayerseemsunabletoplaythestream? Ifthestreamlookstobegettingtotheplayerthenitwillbehowtheplayerishandlingit.Theusualcausesofthis are

Missing".ogg"extension.Bothicesandicecastdonotcareabouttheextensionhoweversomeappsusethe extensiontodeterminewhichplugintouse. MissingOggVorbisplugin.Thewinampliteversionswereknownforthis. AreyourunningWinamp3.Thisisadiscontinuedproductandhadproblemswiththevorbisplugin,eitheruse thelaterv2.9seriesorv5. Thesoundqualityispoor OggVorbisisalossycompressiontechnology,soqualityofthesoundisreduced,howeverwithliveinputthe sourceofaudiocanbepoordependingonthesoundcardandthesystemit'sin.Asaninitialtestjustrecordawav filefromtheDSP(usingegrec,arecordetc)andlistentothequalityoftheaudiorecorded.Ifthesourceofaudio ispoorthenencodingittoOggVorbisisnotgoingtoimproveit. ThereasonsforpooraudiofromtheDSPcanbedifficulttoresolve,searchforinformationonaudioquality.It couldbedriverrelatedormaybesomeinterferencefromsomeotherdevice. Herearesomelinkswherefurtherinformationcanbefound: http://www.djcj.org/LAU/guide/index.php http://www.linuxdj.com/audio/lad/index.php3

IceSv0.4 IceSv.04isasourceclientforbroadcastinginMP3formattoanicecast2server Introduction What'sItFor? WhatCanItDo? Configuring Licensing DevelopersResources

Introduction Foraverylongtime,theonlygoodstreamingtoolforcommandlinesystemswasshout.Shouthadalotofissues, itwasaquickanddirtyhack,itwasbuggy,itwassendingdatatoofastortooslow,anditwasjustsomethingno onewantedtofix.Sowerewroteitfromscratch,andthenextgenerationstreamer,'ices',ishere.'ices'isshortfor 'icesource',asourcefortheicecastserver.'ices'shouldbepronounced'isis'liketheegyptiangodessoffertility.For moreinformationabouticecast,Isuggestyoucheckouttheicecastwebpageathttp://www.icecast.org/.

What'sItFor Ices,armedwithalistofmp3files,sendsacontinuousstreamofmp3datatoanicecastserver.Theserveristhen responsibleforacceptingclientconnectionsandfeedingthemp3streamtothem.Butthestreamoriginatesinthe streamer,'ices'.Theterms'encoder','streamer'and'source'areusedequivalentlythroughoutthisdocument,and throughoutallthedocumentationinthestreamingsystem.

WhatCanItDo CueFile Thecuefileholdsinformationonthefilethaticesiscurrentlyfeedingtotheserver.Thisisneatforyoupeopleout therewholikerunningscripts.Imyself,usethecuefileinatclscript,runningfromaeggdropbot,onirc.That wayIcanaskthebotwhatsongiscurrentlyplaying,howlongitis,howmuchofithasbeenplayed,andget informationaboutthenextsongsontheplaylist. Thefilecurrentlyhasthefollowinglines,(inthisorder). filename size(inbytes) bitrate(inkbits/s) minutes:seconds(totalsonglength) percentplayed(i.e25,no%sign) playlistlineindex(i.e3,ifwe'replayingthe4:thlineintheinternalplaylist.Logical,huh?)Also,foryou scriptingpeople,whenicesstarts,itwritesitsprocessidtothefileices.pid. ID3Artist ID3Title SignalHandling SendingSIGINTtoiceswillmakeitexit. SendingSIGHUPtoiceswillmakeitcloseandreopenthelogfileandplaylist,andreloadandrestarttheplaylist scriptifyouareusingone. SendingSIGUSR1toiceswillmakeitskiptothenexttrack. Reencoding Ifcompiledwithsupportforreencodingusingliblame,andyousupplytheRcommandlineoptionorsetthe Stream/Reencodeto1intheXMLconfigfile,theniceswillstartreencodingyourfilesontheflytothebitrateyou specifiedwiththeboptionortheStream/Bitratetag. Ifyouarereencodingandiceswascompiledwithvorbissupport,youmayalsoreencodeOggVorbisfilesasMP3 onthefly.ThisgivesyoutheopportunitytoconvertyoursourcefilestoOggVorbisatyourconveniencewhilestill supporting as many listeners as possible. Likewise, ices can transcode FLAC and MP4 (AAC) files if you've compileditwithFLACandFAADlibraries,respectively. Thesamplerate,numberofchannels,etc,willbechosenontheflybylameitself,unlessyouspecifysomething usingtheHandNoptions.Ithinkyoushouldbefinewithwhateverlamechoosesthough. Also,pleasemakesurethatyourfilesareokbeforeyoustartreencodingthemwithices.Thisisbecausethempglib partoflame(whatdoesthedecoding)isratherunstableandwillcallexit(0)whenerrorsareencountered. Thiswillmakeicesexit,whichiskindabad:) Crossfading Ifyou'vecompiledwithsupportforreencoding,youcancrossfadebetweentracks(blendtheendofoneintothe startofthenext).ThisiscontrolledbytheCcommandlineoptionorthePlaylist/Crossfadeparameterinthe configurationfile.Bothofthesetakeanintegerargument,whichisthenumberofsecondstocrossfade.Songsless thantwicethelengthofthecrossfaderequestedwillnotbefaded.ThisishandyforegstationIDs. MultipleStreams

Youcanfeedthesameplaylistsimultaneouslytodifferentmountpoints,byspecifyingmultipleStreamsectionsin theconfigfileorpassingmultiplemoptionsonthecommandline.Thisisespeciallyusefulinconjunctionwith reencodingbecauseyoucanstreamthesamemusicatahighbitrateforbroadbandlistenersandsimultaneouslyat alowbitrateforPOTSlisteners. PlaylistHandling About96%ofallemailsIgotaboutshoutwaspeopleaskingmetoaddsmallchangestoshoutplaylisthandlingto suittheirspecificneeds.ThisiscourseisnothowIwanttospendmylife:)Shouthadafeaturetocallanexternal programwithasystem()call,beforeeachsong,andthatcouldpossiblymodifytheplaylist.Thiswasratherugly, butdidthetrick.Inices,wetakethisastepfurtherandincludescriptingsupportinsidetheprogram.Youcan writeyourownplaylisthandlerinperlorpython,whateveryouprefer. Yourscriptmodulehastodefineatleastafunctionnamedices_get_next,whichshouldreturnapathtoafileor FIFOcontainingMP3data. Inadditionyoumaydefinethefunctionsices_initandices_shutdownwhichwillbecalledbyicesoncebefore askingforthefirstsongandbeforeshuttingdown,respectively. Youmayalsodefineices_get_lineno,whichspecifiesthelinenumberofthecurrenttrackinthecuefile.Ifyou don'tusethecuefileitissafetoomitthisfunction. Finallyyoucandefineices_get_metadatatoreturnastringyouwanttousefortitlestreaming.Iceswillcallthis functiononcepertrackaftercallingices_get_next.Ifthisfunctionisnotdefinedorreturnsnull,iceswilluse whateveritcangetoutofthefileitself,eithertagsorthefilename. Isuggestyoutakealookinthedistributedmodulefilesandjustexpandonthat.

Configuring Icescandoeverythingshoutcoulddo,andmore.Itcanbeconfiguredthroughhardcodeddefaults,aconfigfile, andcommandlineoptions.TheconfigfileisinXML,butdon'tgetscaredandrunoff.Justeditthedistributed configfileand change the values you need. Thecommand lineoptionsshould befamiliarto old shoutusers, althoughsomeoptionshavebeenrenamed. CommandLineOptions Options: B(Background(daemonmode)) b<streambitrate> C<crossfadeseconds> c<configfile> D<basedirectory> d<streamdescription> f<dumpfileonserver> F<playlist> g<streamgenre> h<host> i(useicyheaders) M<interpretermodule> m<mountpoint> n<streamname> p<port> P<password> r(randomizeplaylist) s(privatestream) S<perl|python|builtin> u<streamurl> N<Reencodednumberofchannels> H<Reencodedsamplerate> Notethateachtimeyouspecifyamountpointwithmyouarecreatinganewstream,andsubsequentstream optionswillapplyonlytoit. ConfigurationFile(ices.conf) Here'sasampleconfigurationfile.It'sthesameastheices.conf.distthatisincludedintheicesdistribution.You canspecifymultiplestreamsectionswithdifferentmountpoints,names,andreencodingoptions. <?xmlversion="1.0"?> <ices:Configurationxmlns:ices="http://www.icecast.org/projects/ices"> <Playlist> <File>apan.txt</File> <Randomize>1</Randomize> <Type>builtin</Type> <Module>ices</Module> <Crossfade>0;<Crossfade> </Playlist> <Server> <Hostname>localhost</Hostname> <Port>8000</Port> <Password>letmein</Password>

<Protocol>xaudiocast</Protocol> </Server> <Execution> <Background>0</Background> <Verbose>1</Verbose> <Base_Directory>/tmp</Base_Directory> </Execution> <Stream> <Name>CoolicesdefaultnamefromXML</Name> <Genre>CoolicesgenrefromXML</Genre> <Description>CoolicesdescriptionfromXML</Description> <URL>CoolicesURLfromXML</URL> <Bitrate>128</Bitrate> <Public>1</Public> <Reencode>0</Reencode> <Samplerate>1</Samplerate> <Channels>1</Channels> </Stream> </ices:Configuration> Configurationsoptions Thisdescribesallthedifferentoptionsinices. ServerHostname Commandlineoption:h<host> Configfiletag:Server/Hostname This is the name, or ip, of the host ices should connect to. It has to run a streaming server, capable of the xaudiocastoricyprotocol. Thisvaluedefaultstolocalhost. ServerPort Commandlineoption:p<port> Configfiletag:Server/Port Thisistheporttheserverislisteningon,bydefault8000. ServerPassword Commandlineoption:P<password> Configfiletag:Server/Password Theencoderpasswordfortheserver.Ifthisisnotcorrect,thenicescannotloginontheserver,andiceswillexit. ServerProtocol Commandlineoption:iforicyheaders Configfiletag:Server/Protocol Eitherxaudiocastoricy.Usexaudiocastifyoucan,andicyifyoumust. ExecutionBackground Commandlineoption:B Configfiletag:Execution/Background Thiswilllaunchicesinthebackground,asadaemon. ExecutionVerbose

Commandlineoption:v Configfiletag:Execution/Verbose Normallyicesoutputswhatstreamisplayingandasmallamountofextrainformation.Withverboseturnedon, yougetawholelotofdebugginginformationandlotsoftrackinfo. ExecutionBaseDirectory Commandlineoption:D<directory> Configfiletag:Execution/Base_directory Icesusesthis directory forcuefiles, log files and temporary playlist files. You need writepermissionsin this directory.Thedefaultis/tmp StreamMountpoint Commandlineoption:m<mountpoint> Configfiletag:Stream/Mountpoint Thisisthemountpointofthestreamontheicecastserver,ifusingthexaudiocastprotocol. StreamName Commandlineoption:n<streamname> Configfiletag:Stream/Name Thisisthenameofthestream,nottobeconfusedwiththenameofthesongplaying. StreamGenre Commandlineoption:g<streamgenre> Configfiletag:Stream/Genre Thisisthegenreofyourstream,e.gJazzorStatic. StreamDescription Commandlineoption:d<streamdescription> Configfiletag:Stream/Description Thisoptionisadescriptionofyourstream. StreamURL Commandlineoption:u<URL> Configfiletag:Stream/URL ThisshouldbeaURLdescribingyourstream. StreamBitrate Commandlineoption:b<bitrate> Configfiletag:Stream/Bitrate Ifyouturnonreencodingthenthiswillbethebitrateofthestream,otherwizetheactualbitrateofthestreamis thebitrateyourfilesareencodedat,andthisvalueisfordisplayingpurposesonly. Readthelast3linesagain,please. StreamPublic Commandlineoption:s(makesstreamprivate) Configfiletag:Stream/Public

Thisregulateswhethertheicecastserverwilldisplayyourstreamonadirectoryserver.Defaultis1(yes). StreamReencode Commandlineoption:R(turnsreencodingon) Configfiletag:Stream/Reencode Whenyouturnthisoptionon,ices(ifcompiledwithlibmp3lamesupport)willreencodeyourmp3filesonthefly towhateverbitrateyouspecifywiththeStreamBitrateoption,unlessthefilebitrateisthesameasthestream bitrate. PLEASENOTE:thatifyourfilesarecorrupt,thismightcrashicesbecausethelibraryusedtodecode(mpglib)is notverystable.Isuggestyoucheckyourfileswithmp3checkorsomeothermp3verificationprogrambeforeyou addthemtoyourplaylist.Justpoppingthemintoyourfavouriteplayerandcheckingthesoundisdefinitelynot enough. Forlegalreasons,thisoptionisnotavailableonthebinarydistributions. StreamSamplerate Commandlineoption:H<samplerate> Configfiletag:Stream/Samplerate Usethistoforcereencodingtooutputmp3datawiththissamplerate. StreamChannels Commandlineoption:N<numberofchannel> Configfiletag:Stream/Channels Usethistoforcereencodingtooutputmp3datawiththismanychannels. PlaylistFile Commandlineoption:F<file> Configfiletag:Playlist/File Thisisthefilewhereicesoriginallylooksforfilestoplay. Whenusingplaylistmodulesinperlorpython,thisargumentisignored. PlaylistRandomize Commandlineoption:r(randomizesfile) Configfiletag:Playlist/Randomize Thisoptionispassedtotheplaylisthandler,andtellsittorandomizetheplaylist. PlaylistType Commandlineoption:S<perl|python|builtin> Configfiletag:Playlist/Type Bydefault,icesusingabuiltinplaylisthandler.Ithandlesrandomizationandnotmuchmore.Mostpeoplewant sophisticated playlist handlers that interface with databases and keep track of god knows what. ices handles embeddedpythonandembeddedperl,sonowyoucanwriteyourownmodules,withoutmodifyingices,thatdo justaboutanything.Usethisoptiontochangetheplaylisthandlertypefrombuiltin(default),topythonorperl. PlaylistModule Commandlineoption:M<module> Configfiletag:Playlist/Module Usethisoptiontoexecuteadifferentpythonorperlmodulethanthedefault.

Defaultforpythonisices.pyanddefaultforperlisices.pm,althoughdoNOTspecifythefileextensionforthe module.Use'whatever'insteadof'whatever.pm'or'whatever.py' Crossfade Commandlineoption:C<seconds> Configfiletag:Playlist/Crossfade Ifthisoptionisspecifiedandreencodingisenabled,iceswillcrossfadesecondsbetweentracks.

Licensing IcesislicensedundertheGnuGeneralPublicLicense,andformoreinfoaboutthatIsuggestyoureadthefile namedCOPYING.

Developersresources If you want to write your own streaming software, or perhaps a nice streaming mp3 client, go to http://developer.icecast.org. ThisdocumentwasmostlywrittenbyAlexanderHavng[eel@icecast.org].

SourcingMultimediaContentWithTheVideoLanClient(VLC) Introduction InstallingVLCWithlibshoutSupport CommandLineSyntaxForStreamingContentToAnIcecastServer VLCIcecastOutput(CommandLineOptions)

Introduction TheVideoLanClient(VLC)canbeusedtosourcemultimediatoanIcecastserver.Themultimediacontentthatis beingsourcedmustbecompatiblewiththeOgg,MP3format. YoumustenableVLCtosupporttheIcecastOutputmethodtoallowVLCtosourcemultimediatoanIcecastserver. Thisisdonewiththeadditionandenablingofthelibshoutlibrary.Precompiledpackagesdonotautomatically enablethelibshoutlibrary.

InstallingVLCWithlibshoutSupport (ForDebianLinux) Installlibshout. #sudoaptgetinstalllibshoutdev InstallVLC. #sudoaptgetbuilddepvlc ConfigureVLCtoenablelibshoutsupport. #./configureprefix=/opt/vlc0.8.6x/execprefix=/opt/vlc0.8.6x/enabletheoraenableshoutenablev4l enabledvb Compile. #make #makeinstall CheckVLCtoensurethatlibshoutsupporthasbeenenabled. #cd/opt/vlc0.8.6x/bin #./vlcl|grepshout Iflibshoutsupporthasbeenproperlyenabledyouwillgetthisprintout. #VLCmediaplayer0.8.6aJanus #access_output_shoutIceCASToutput #playlistNewwinamp5.2shoutcastimport #shoutShoutcastradiolijsten #shoutShoutcastTVlistings http://forum.videolan.org/viewtopic.php?f=4&t=14476&start=30

CommandLineSyntaxForStreamingContentToAnIcecastServer streamsinglemultimediafile :duplicate{dst=std{access=shout,mux=ogg,dst=source:hackme@192.168.1.6:8000/audio.ogg}} streammultimediafrominput :std{access=shout{name="mystream"},mux=ogg,dst=source:hackme@192.168.1.6:8000/audio.ogg}" source=server_password@server_ip_address:portnumber/stream_name.ogg http://forum.videolan.org/viewtopic.php?f=4&t=14476&start=30 Note: Youmustalsoincludeinformationadditionalinformationinthecommandlinesyntax,suchasthesourceofthe filesorinputdeviceandifyouintendtotranscodethemultimediacontentintoanothercodec. http://www.videolan.org/doc/streaminghowto/en/ch03.html

VLCIcecastOutput(CommandLineOptions) soutshoutname=<string>(Streamname) Nametogivetothisstream/channelontheshoutcast/icecastserver. soutshoutdescription=<string>(Streamdescription) Descriptionofthestreamcontentorinformationaboutyourchannel. soutshoutmp3,nosoutshoutmp3(StreamMP3(defaultdisabled)) YounormallyhavetofeedtheshoutcastmodulewithOggstreams.ItisalsopossibletostreamMP3instead,so youcanforwardMP3streamstotheshoutcast/icecastserver.(defaultdisabled) soutshoutgenre=<string>(Genredescription) Genreofthecontent. soutshouturl=<string>(URLdescription) URLwithinformationaboutthestreamoryourchannel. soutshoutbitrate=<string>(Bitrate) Bitrateinformationofthetranscodedstream. soutshoutsamplerate=<string>(Samplerate) Samplerateinformationofthetranscodedstream. soutshoutchannels=<string>(Numberofchannels) Numberofchannelsinformationofthetranscodedstream. soutshoutquality=<string>(OggVorbisQuality) OggVorbisQualityinformationofthetranscodedstream. soutshoutpublic,nosoutshoutpublic(Streampublic(defaultdisabled)) Maketheserverpubliclyavailableonthe'YellowPages'(directorylistingofstreams)ontheicecast/shoutcast website. Requires the bitrate information specified for shoutcast. Requires Ogg streaming for icecast. (default disabled) http://wiki.videolan.org/VLC_commandline_help