SC_NSV

by Jay Krivanek
===============
####################
# License
####################

WARNING: sc_nsv is beta sofware, it could under certain circumstances seg fault
(crash) or cause system instability or even data loss, do not continue use if
you are not comfortable working with beta software in console environments.

As of this version only videos which have a frame rate that is a whole number
can be broadcasted through sc_nsv, for instance 15, 20, 24, 30 etc NOT 29.97 etc
although I will implement as soon as I can.

sc_nsv is copyright protected and property of Jay Krivanek and www.radiotoolbox.com
and is so for all versions.

sc_nsv may be distributed in it's original archive file packaging, but may not be unpackaged
for the capability to distribute files seperately without the expressed permission
of Jay Krivanek.

To the maximum instant allowed by law Jay Krivanek and www.radiotoolbox.com disclaim
all warraties regarding this software, express or implied, including but not
limited to the warranties of merchantability and fitness for a particular purpose.
In no event shall Jay Krivanek or www.radiotoolbox.com be held liable for consequential,
special, incidental or indirect damages arising out of the use or inability to use this
software even if Jay Krivanek or www.radiotoolbox.com is aware of the possibility of such
damage or known defect.

Jay Krivanek and www.radiotoolbox.com reserve the right to make modification to these
terms as we see fit and without your consent.

By using this software you agree to the terms as they have been presented above.


####################
# Quick Introduction
####################

What is sc_nsv?
---------------
sc_nsv is a application developed for the POSIX enviornment which allows users to
source NSV streams from a unix box.  It's goal is to be simple, so no GUI!

Essentially this application was written to bring the capabilities of Nullsoft's
nsvscsrc program to the unix environment.

What is NSV?
------------
NSV is a Video/Audio Container format developed by Nullsoft Inc.
IT IS NOT A COMPRESSION FORMAT!!
Therefore, sc_nsv does not decode or encode to any compression, it simply reads
NSV files and transfers them at the proper transfer rate to allow comfortable
smooth video for your viewers.

Will there be a Windows version?
--------------------------------
I don't know, maybe, if I have time, but really POSIX is the core of this project
as they do not have alternatives, Windows users should use the tools over at
www.nullsoft.com/nsv/ as they were developed by Nullsoft.

Is sc_nsv open source? Where can I get the source?
--------------------------------------------------
Currently sc_nsv is not open source, however this may change depending
on my time and whether there is interest.  Hence there is no source
code available for sc_nsv.

What operating systems can I run distributions on?
--------------------------------------------------
The hope is to cover the alternatives to Windows, but I am limited to the
systems that I can run and test this on.

The only systems I have tested this on are
- RedHat 7.3
- FreeBSD 5.2

If you are able to get it to run on other Linux flavors please let me
know so I can add them to the supported OS's list

###############
# Configuration
###############
your package should include a file called sc_nsv.conf, feel free to edit this
file to customize your sc_nsv experience, documentation is included in this
file.  You may also specify the location of a configuration file at command
line, for instance ./sc_nsv my_nsv.conf, great for multiple streams.

##########
# Features
##########
- Autoreconnect if the server disappears, the source application waits 30 seconds
  before attempting to reconnect.
- Screen and File logging, so you know what's going on with sc_nsv
- RealTime Display of Outgoing bitrate, NSV Video and Audio Formats as well as
  fps and title of current video
- PLO playlist format, designed by Jay Krivanek of Radio Toolbox; an object
  based playlisting system allowing you to structure content on a clock wheel.
- Basic playlist file system as an alternative if you want to do all the work
  yourself :)
- PLO playlist format includes features like #reload #shuffle which tell
  sc_nsv when the proper times to shuffle and reload are and based off of
  which list you would like the action to occur
- TRUE shuffle logic based off of Hardware CD Player style which plays items
  off of playlist in a random order as opposed to just randomly picking items
  from a list which is NOT technically shuffling ;) hint hint
- PLO supports a virtually unlimited amount of playlist objects.
  For more information about PLO read the Playlist section of this document.
- Reading of the TITLE tag of NSV headers, this will be displayed to your
  users in through meta data titling, you can also use URL to specify a url
  to be sent to your users.  MAKE SURE THAT TITLE IS CAPITALIZED Title or title
  will not be understood, if TITLE is not found the file's name is passed.
- Dynamic Subtitles with profiles and scripting.  Read README for more information
  on the scripting.

####################
# Runtime Management
####################
sc_nsv has new signal handling capabilities allowing you to control the sc_nsv
process in real time.  The following signals, when sent, will perform the action.

Signal    Action Performed
======  | ================
SIGHUP    flushes log file or empties contents of log file.
SIGUSR1   reloads the playlist (careful with this one, if your playlist
          file doesn't exist or is unreadable/unparsable the program will exit!)
SIGUSR2   switches track position to next position. (closes source current file)
SIGWINCH  reloads the configuration file, network and stream details will take effect
          until sc_nsv gets disconnected and auto reconnects.

##########
# Playlist
##########
The playlist is probably the only feature that sets sc_nsv apart from 
nsvscsrc.  Any lines beginning with whitespace or a simi-colon character are
ignored. The playlist commands are prepended with a # character and if the
command specifies a list it will end with a # character. Commands which are
capitalized may only be specified once, otherwise an error will occur and
sc_nsv will abruptly halt.

A list of available commands:
#Mode=<mode>
#cd <directory>
#define <name>
#list <name>
#clock
#include <file>
#reload
#shuffle <optional arg secs>

#list and #clock are structures which take up more then once line and have
more then one arguement.
#include, #reload, and #shuffle may only be called from within user defined
objects or structures.  For a clearer understanding of the syntax or a
quick and dirty look (if you aren't much for reading) view the
included playlist.plo file.

IMPORTANT: the plo language is case sensitive so #list me: and #list: Me: are
different containers.

Simple commands, a simple command just gets written like so:
#command <optional arg>

sc_nsv does not currently ignore whitespaces on parsable lines so be careful!

command structures or containers are written like so:
#command <optional arg>:
item
item
item
#

note the colon at the end of our first statement.  Items within in the
container are taken literally from the line in which they reside
so if the line is

/mycat sux ; goat balls //and more

sc_nsv will read it as that. only ending the item at the newline or end of line.

Now for a little detail on each command.

The playlist can be set in 2 different modes.  Basic or Object.

In Basic mode the playlist runs just as a list of files, each line specifying
a new item for the list.

For Example:
#Mode=Basic
/path/to/video/file1.nsv
/path/to/video/file2.nsv
/path/to/video/file3.nsv

in this example our file just has 4 lines, the first line sets sc_nsv to 
parse the playlist in Basic mode, the rest fill a rudementary list.  There
is really no thought here, sc_nsv will simply start with file1.nsv and work
it's way down to file3.nsv and start the process over.  There is no shuffle
feature for this mode currently.

In Object mode, you create containers or playlist objects, so in essence
you can have a very large number of different playlists which hold certain
categories of files.  sc_nsv will use the #clock object to determine the ordering
of which object to pull the next file from.  It also keeps track of which
item has already played and continues down the list no matter how long it's
been since you accessed the playlist container

For Example:
; This is a comment
#Mode=Object

#define ourplaylist
#define breaks

; Here we have defined 2 playlists, these will become containers

; Now we fill our containers, or playlists
#list ourplaylist:
/path/to/video/file1.nsv
/path/to/video/file2.nsv
/path/to/video/file3.nsv
#

; We have now created a playlist that has 3 items in it we gave that playlist
; the name ourplaylist

#list breaks:
/path/to/break/file1.nsv
#include /path/to/generated.plo
#reload
#

; Now I have stepped it up a notch, with this object we have filled it
; with /path/to/break/file1.nsv and a list of files from /path/to/generated.plo
; the included file WILL BE read as a Basic playlist automatically so
; no need to define #Mode=Basic inside of it.

; I then called #reload, which basically says, when we get to this position
; of this playlist, relaod the entire playlist file from the hard disk.
; #shuffle, #include, and #reload basically all work on this same premise.
; They are executed in the order they are in the list, so it would be wise to
; do your #shuffle at the top of a list like so:

#list breaks:
#shuffle
/path/to/break/file1.nsv
#include /path/to/generated.plo
#reload
#

; during a shuffle the #shuffle position is not lost nor is #reload and #include
; is simply parsed long before the shuffle process begins so it is never
; seen.  Also note that #shuffle can have an optional parameter.
#shuffle 3600
; which tells sc_nsv to only shuffle if it's been 3600 seconds since the last
; shuffle.  And the shuffler will play all items in the playlist before repeating
; the playlist again.

; Some final notes, about commands that I feel are important for you to realize
; cd= will change the internal current working directory which means ALL files
; which have not been specified with absolute paths will be subject to odd
; things, so be sure you know when and why you are using cd= cd= is a global
; command and cannot be used withing playlist objects.  Also, #reload
; releases #shuffle <param>, so using the 2 together in the same object will produce
; unexpected results if you have shuffle set to a interval,  If you do have
; #shuffle and #reload as they are above then after each #reload the #shuffle is performed.
; whether or not there is a logical solution to the #shuffle interval with #reload
; delima will determine whether this is fixed, thoughts are #reload <interval> would
; be a better way to handle this problem or setting #reload to the same interval
; as shuffle automatically.  Chances are this delima will be cured in the next
; release, one way or another.

;
; Clock Positioning is NOT changed when a command item is met in the playlist
; object therefore the appearence of the stream to play items at the proper
; interval will not change however the log may look as if it is pulling
; an item from an object too many times, THIS IS A FEATURE.  It allows you
; to debug your playlist objects and understand the logic sc_nsv is following.

; Now for the final and most important key that brings it together, #clock:
; #clock is just like a defined playlist object, except a #shuffle, #include,
; and #reload should not occur here.  The only items which appear in a #clock
; container are the defined playlist names in the order at which you wish them
; to play.

For example:
#clock:
breaks
ourplaylist
ourplaylist
ourplaylist
#

; in this example an item is pulled from each list as they occur in order
; from the clock container, in a first iteration of this object you could
; use the example from above to determin how play progress will occur.

For example
/path/to/break/file1.nsv
/path/to/video/file1.nsv
/path/to/video/file2.nsv
/path/to/video/file3.nsv
; Here the clock starts all over again.
/path/to/break/file2.nsv
/path/to/video/file1.nsv
/path/to/video/file2.nsv
/path/to/video/file3.nsv

This process occurs infinately giving your audience that nice structured feel
to your broadcast.

If you find any logic bugs in the PLO format please contact me through
forums.radiotoolbox.com and let me know how you think it should work.
Be clear on why it's not working as you expect it to.

###########
# Subtitles
###########

sc_nsv supports creating it's own subtitles dynamically, much like you can do
with nsvcap but with static files.  I have included some Subtitle modes just
for testing reasons or if you wanna play, things like a clock, sc_nsv output
or file tagging.  While these things may look great on the outside they may,
with the exception of the tagging feature, be annoying for your viewers.  So
please try to be a little careful playing around with this. :)

Beside that you can use the SCRIPT mode which allows you to create a file
called subtitle.txt.  This gives you an interface to the NSV subtitle engine
written withing sc_nsv.  With this file you can do some interesting and
interactive things with your stream, but I stress that it may be annoying to some
if you do too much or display too much, so take care in messing with this feature
as well.

A description of the subtitle.txt file is as follows, and feel free to mess with
the included subtitle.txt file in order to gain a greater understanding of how it
works.

######## Beginning of subtitle.txt
<persistance> <frames before update> <x position> <y position> <red value> <green value> <blue value>
...
######## End of subtitle.txt

It is very important that the file have a subtitle header as the first line!

<persistance> is whether or not the title should remain on screen after frames
before update has expired.  A setting of 0 means that the title will disappear
after <frames before update> has passed.  A setting of 1 means that the title
will simply refresh after <frames before update has passed.

<frames before update> is the amount of frames that pass before the client will
discard the subtitle.  this becomes a refresh rate if you have persitance on.  For
smoother persistance make sure this value is a multiple of your frame rate.  IE
192 is 8 seconds for a 24fps file.  24 is 1 second for the same file.  Fractioning
this will cause the subtitle to appear to glitch.

<x position> is the subtitle's x position or horizontal position on screen.  This
is based on a value of 0 - 255, 0 being the left most portion of the screen and
255 being the right most portion.

<y position> is the subtitle's y position or vertical position on screen.  This
is based on a value of 0 - 255, 0 being the top most portion of the screen and
255 being the bottom most portion.

The screen coordinate system patches right into the subtitle header and it is up
to the client to handle this properly.  For instance Winamp will place the subtitle
on positions in such a way that they do not leave the screen unless they have to or
run out of screen space.

<color value> red green and blue work the same way.  0 would be the lack of the
specified color and 255 would be the inclusion of the specified color with
variation in between.  Examples would be White: 255 255 255 Red: 255 0 0
Purple: 255 0 255 Yellow: 255 255 0 Cyan: 0 255 255 Grey: 125 125 125 Black: 0 0 0

View subtitle.txt to see an example of it's usage.

The lack of the first line or any of the params of the first line will produce
undefined results, so make sure to include all parameters in your subtitle file.

Any text below the first line sc_nsv will attempt to include in the subtitle
and they will be displayed with their new line values.

########
# Credit
########

SHOUTcast is a Registered Trademark of Nullsoft Inc.
NSV is a proprietory format of Nullsoft Inc.

sc_nsv is copyright Jay Krivanek

#####################
# Known Issues (bugs)
#####################

- Supports framerates which are whole numbers ONLY, this will probably be fixed
  soon, so you fractional framerate lot may not get much use out of this tool.

#################
# Version History
#################

sc_nsv 1.0.0
- Fixed icy-url bug, meta url's should now be handled more to spec.
- compiled for freebsd now (so now Freebsd can use something native :)
- fixed playlist starting on item 2 after #reload bug

sc_nsv 1.0.0 beta 2
- Hostname lookups added.
- Fixed Audio Sync bug, (yay)  Tested with VP6 and VP3 with MP3 audio
- Fixed Log, various screen to file log problems
- No longer opens two handles to the currently playing file.
- Dynamic Subtitle support added
- signal handling added, read the README file section Run-Time Management
  for more details.
- Autoreconnect stuff fixed
- sc_nsv now statically linked so that it may work on FreeBSD in linux emulation.
- shuffling is now more random.

sc_nsv 1.0.0 beta 1
- Initial version