Documentation Version 1.0
May 1, 2010
--------------------------
LCM Addon:
--------------------------
A "Smart Video Networking" Project by Andre Govier, Eric Gustavson, Ron Laidley.

--------------------------
Abstract:
--------------------------
This small C software package uses LCM (http://code.google.com/p/lcm/) and FFMPEG (http://www.ffmpeg.org/) to send video files over a LAN. A file is sent using the UDP Multicast protocol via LCM. Once it is received, it is broken up into individual images (and written to file).

[Notes]
-Networking tasks are handled by LCM
-Video tasks are handled by FFMPEG

--------------------------
Full Description:
--------------------------
A server machine takes a single video file as input (usually either .avi or .mpg/.mpeg). When the server sends the file, it first breaks it up into 1-second sub-videos, and sends those at a default rate of 1 per second. The process of splitting videos is done through calls to FFMPEG over the linux command line. The process of sending the sub-videos is done through integrated LCM code. All client machines running the listener recieve the packets via LCM. As the 1-second sub-videos are recieved by each client, they are decomposed into individual frames, and written to file as ppm images (one per frame). 

--------------------------
Website:
--------------------------
http://occulens.com/svn/
http://code.google.com/p/lcm-addon/

--------------------------
Dependencies:
--------------------------
Unix/Linux Command Line
LCM
FFMPEG

--------------------------
Testing Environment:
--------------------------
This product has been tested as working with server and client machines running Ubuntu 9.10, with LCM version 0.4.0 and FFMPEG version 0.5.1 installed. Sending and recieving files has been successful locally (on a single machine), as well as between machines (through router).

--------------------------
Environment Setup:
--------------------------
1)Install LCM:
http://code.google.com/p/lcm/downloads/list
-download version 0.4.0
-install

2)Install FFMPEG
http://www.ffmpeg.org/download.html
-download version 0.5.1
-install

--------------------------
Using LCM Addon:
--------------------------
1)run ./gen to install the program in the local directory
2)run ./listener on all client machines
3)run ./send-video <video_file> to send a video file to all listening clients

[Notes]
4)run ./tidy to clean up temporary files and images in ./output/
5)run ./clearout to delete all images in ./output/

--------------------------
Files & Folders:
--------------------------
[scripts]
gen - installation & build script
tidy - clean script
clearout - delete output images script
Makefile - for building code (automatically called by gen - use gen instead of Make)

[source]
example_t.lcm - LCM-specific config file. Describes container for sending video packets.
listener.c - Client-side. Recieves images, and calls decode_video.
decode_video.c - Client-side. Splits 1-second sub-videos into images. Calls image_handler.
image_handler.c - Entry point for image/frame interpreter. Default action: write individual frame to ppm file. Can be extended/modified to do something else (like send frame data to another program)
send_video.c - Breaks an input video into 1-second subvideos, and then calls send_message to send the subvideos.
send_message.c - Sends packets to listeners over LCM.

[executeables]
listener - listener to be run on all client machines
send-video - sender to be run on server machine. Run once per video to send.

[directories]
tmpsplit - Server-side. Temporary storage for 1-second sub-videos. Generated and deleted automatically when a send completes.
tmpvid - Client-side. Temporary storage for 1-second sub-videos. Generated and deleted automatically when a recieve completes.
output - output images saved here.

--------------------------
Configurable Variables:
--------------------------
[Network Tweaks]
VIDEO_DELAY in send_video.c:
delay in 1/100secs between sending each sub-video (default = 100)
PACKET_DELAY in send_message.c
delay in seconds between each packet (default = 10)

[Video Compression]
USER_BITRATE[25] in send_video.c
set FFMPEG flags to determine video compression on the server side