ESA

From Acorn

EasySAPAnnouncer (ESA) beta 0.2.0 Draft documentation

Contents

[edit]

Introduction

ESA creates standard SAP announcements that will be recognized by VLC and other SAP listeners, from:

  1. SDP files created by QT Broadcaster running in multicast mode
  2. SDP files created by Wirecast running in multicast mode
  3. Multicast relays from playlists in QuickTime Streaming Server, OSX 10.5.4
  4. Has also been tested with some standard SDP files

In above cases, streams were RTP H.264 MPEG4 streams. ESA should also handle any standard SDP file. Since ESA is just sending out the SDP announcements it doesn't care about the actual media stream compatibility. Of course client and server compatibility is a whole different matter.

This has been tested to run on OSX 10.5.3 and 10.5.4, Intel Processor.

Should also run on Intel or PowerPC Mac with OSX 10.2 or later, not tested.

Tested on Linux Ubuntu 8.04, Windows XP SP3 and Vista.

[edit]

Download and Installation

On Mac, Control-Click and Download Linked File. On Windows, Right-Click and Save Target As:

http://nutmeg.conncoll.edu/wiki/EasySAPAnnouncerMacBeta0.2.0.dmg

http://nutmeg.conncoll.edu/wiki/EasySAPAnnouncerLinuxBeta0.2.0.zip

http://nutmeg.conncoll.edu/wiki/EasySAPAnnouncerWindowsBeta0.2.0.exe

  1. OSX: Uncompress .dmg, and drag ESA to Applications.
  2. Ubuntu: Open Zip, Install on desktop. It will work here, other locations not tested.
  3. Windows XP and Vista: Open Zip, run installer.
[edit]

Preferences Settings


  1. Go to Preferences. Select the default scope you would like to use for all new sessions. You can change the scope of individual sessions at any time later. Use the + Plus button to define a new scope.
  2. Shift-click on the + Plus button to restore default scopes.
  3. TTL or any Scope Name can be changed by clicking on it. TTL is initially set to 8, as a safety feature.
  4. Set Session Announcement Interval for all announcements.
  5. The Optional VLC Program Group inserts the line “a=x-plgroup:Name” into the SDP files. This enables VLC to group all streams in one Program Group.
  6. There is a check so that ESA does not add the “a=x-plgroup:” line if the SDP already has one. This has the nice benefit that you can manually add a unique “a=x-plgroup:” line to a few sessions, and all the others would still have the standard “a=x-plgroup:” line added automatically.
  7. Click “OK”
[edit]

Fixing Wirecast SDP files

VLC 0.9.4 does not detect Wirecast SDP files unless they are modified. Here is an example:

Original file:

v=0

o=- 82811671 82811671 IN IP4 127.0.0.0

s=Wirecast

t=0 0

a=range:npt=now-

m=audio 5432 RTP/AVP 96

c=IN IP4 233.88.214.139/99/1

a=rtpmap:96 mpeg4-generic/44100/2

a=fmtp:96 profile-level-id=15;mode=AAC-hbr;sizelength=13;indexlength=3;indexdeltalength=3;config=1210

m=video 5434 RTP/AVP 97

c=IN IP4 233.88.214.139/99/1

a=rtpmap:97 H264/90000

a=fmtp:97 packetization-mode=1;profile-level-id=4D401E;sprop-parameter-sets=J01AHqkYFAe2ANQYBBrbCte98BA=,KN4JF6A=

a=cliprect:0,0,480,640

a=framesize:97 640-480

b=AS:1500


To fix it move the b=AS:1500 line to go just below the video c=IN line, and add ONE carriage return at the end of the file. If you don't have the carriage return, or have TWO, the SAP is not detected by VLC 0.9.4. This results in this file, which works:

v=0

o=- 82811671 82811671 IN IP4 127.0.0.0

s=Wirecast

t=0 0

a=range:npt=now-

m=audio 5432 RTP/AVP 96

c=IN IP4 233.88.214.139/99/1

a=rtpmap:96 mpeg4-generic/44100/2

a=fmtp:96 profile-level-id=15;mode=AAC-hbr;sizelength=13;indexlength=3;indexdeltalength=3;config=1210

m=video 5434 RTP/AVP 97

c=IN IP4 233.88.214.139/99/1

b=AS:1500

a=rtpmap:97 H264/90000

a=fmtp:97 packetization-mode=1;profile-level-id=4D401E;sprop-parameter-sets=J01AHqkYFAe2ANQYBBrbCte98BA=,KN4JF6A=

a=cliprect:0,0,480,640

a=framesize:97 640-480


There are two settings in VCL under Services discovery, SAP

1) Try to parse announcement (default is on). The SAP module in VLC parses announcement, otherwise parsed by the "live555" (RTP/RTSP) module.

2) SAP strict mode (default is off). SAP parser will discard some non-compliant announcements.

It does not make any difference in the above SDP what the settings are, after the changes are made, it always works. Now, on to the RFC to see who is wrong!

[edit]

Main SAP Announcement List window

  1. Drag a multicast SDP file into the ESA main window. Session name is pulled from the “s=” line in the SDP file.
  2. SDP files can also be imported using the “File>Open SDP File” menu.
  3. By default, sessions are initially active (check box enabled).
  4. There is some basic error checking (see Appendix a). If a value or scope is invalid in some way it will show it in red so you'll know to investigate.
  5. The window displays Session Name, SAP Scope, TTL, Next Announce time, and Count of announcements.
  6. Select a different SAP scope for a session using the popup menu in the SDP editing window. Use the Preferences dialog to change scope properties such as the multicast address or TTL.
  7. Right-Click (or Control-click) on a session to see a list of useful commands in the contextual menu. You can operate on many sessions at the same time by using Shift-click or Command-click to select multiple sessions simultaneously.
  8. Click a column heading to sort. Click again to sort in reverse order.
  9. If you double-click on the session name, its SAP Announcement window opens:



Here edits can be made to the imported SDP file. Selecting Update implements the changes internally in ESA. The original SDP file is not changed, but a new one can be exported.

[edit]

Useful statistical displays

  1. In the main SAP Announcement List window: For each SAP: Scope, TTL, Next announce time and count. In the lower left: Number of Sessions, SAPs sent, kilobytes sent, Queue (see Appendix b), Bandwidth (BW) in kilobits/sec. Bandwidth is displayed as Current Bandwidth/Maximum Bandwidth. Hold SHIFT and click on the statistics to reset them to zero.
  2. In SAP Announcement window for each announcement: SDP file, Scope, IP, Port, and TTL.
[edit]

Preferences Files

ESA uses two preferences files: “Preferences” and “Session List”. In OSX, preferences are saved in ~/Library/Preferences/Easy SAP Announcer/. In Windows, Preferences are stored in ~/Application Data/Easy SAP Announcer/, on Linux in ~/Easy SAP Announcer

  1. “Preferences” stores ALL of the values shown in the Preference pane, plus the UI state, such as the size and position of the main SAP Announcement List window, and the list box column widths. When you move or resize the window or resize the columns, they are remembered and restored the next time you start up ESA.
  2. “Session List” contains all of the data for each session including the SDP text itself, the SDP file name, the ScopeID and whether the session is enabled. This file is saved after the first time you quit ESA, and refreshed on subsequent quits.
  3. The user can delete either file, while ESA is quit, and ESA will create a new one.
  4. You can also hold SHIFT during launch to get a fresh Preferences file.
[edit]

Appendix

[edit]

ESA Basic Error Checking

  1. This is basic and mostly validates the scope properties. Is the address field a valid IP address in the multicast range? Is the TTL a number from 0-255? Is the port a reasonable number?
  2. If one of these is found to be invalid, that specific field in the scopes list will be red. And if that scope is being used by any of the sessions, the entire session row will be in red. And that session won't be announced at all. You'll notice that the sent count doesn't increase.
  3. The SDP files themselves also have a basic validation. They must be less than 10kB, and include a v= line and a subsequent s= line. This is to prevent someone from accidentally dragging in any old file and avoid accidentally multicasting their favorite photo. :-) If the file is over 10k or isn't an SDP typed file then ESA won't import it at all. If it passes those tests but doesn't have the proper v= and s= lines then it will be listed in the sessions list in red but will not be announced.
[edit]

Explanation of Safety Features and Queue

  1. ESA includes a rate limiter to smooth out the traffic it sends, and to prevent ESA from ever creating a SAP storm. The rate limiter works by putting outgoing SAP announcements into a queue and then sending them out at a smooth rate. The queue can hold up to 100 pending announcements and ESA will send out one pending announcement every tenth of a second.
  2. This means that ESA will never send more than 10 announcements per second. Since each announcement contains approximately 1k Byte of data, this means that the announcement traffic should never be more than about 80 kbps.
  3. ESA's fastest announcement interval is 30 seconds. At a maximum rate of 10 announcements per second ESA can thus handle 300 sessions in the session list. ESA can handle even more sessions if you use longer announcement intervals.
  4. The Queue statistics, in the lower left of the SAP Announcement List window, tell you the peak load that ESA has seen. Here's what the three numbers, Current Queue Count / Maximum Queue Count / Total Queue Size, mean:
  5. Current Queue Count tells you how many items are currently in the queue. In lightly loaded scenarios an item will be in the queue for only 0.1 second. So this number is likely to be 0.
  6. Maximum Queue Count tells you the maximum number of announcements that have ever been in the queue. It represents the peak load since ESA was started up.
  7. Total Queue Size shows you the predetermined size of the queue. Currently it's set to 100.
  8. If the Current or Maximum counts reach 100 it means that there were too many announcements to fit into the queue and the rate limiter discarded the excess announcements until the rate subsided.
  9. The Current and Maximum Counts will probably be much much less than 100 unless you are announcing several hundred sessions.
  10. ESA has been tested with an increasing number of sessions and with a 30 second announcement interval, and the rate limiter kicks in just as expected at 300 sessions. Less than 300 sessions are handled by the queue with no loss, more than 300 sessions cause the rate limiter to discard the excess announcement packets.
[edit]

Exception Reporting Screen

If you get the screen below, please send it to the developer.

[edit]

Contact Information

For comments and suggestions, please email Frank Fulchiero, fful@conncoll.edu

ESA has been developed by Joe Huber, at Talasoft

Retrieved from "http://nutmeg.conncoll.edu/wiki/index.php/ESA"
Views