VLC Broadcasting API
From Justin.tv API Wiki
Contents |
Introduction
About Jtvlc
Jtvlc is a new cross-platform console application that enables you to broadcast to Justin.tv using VLC, a popular video player available for Windows, Mac, and Linux. Pease contact jtvlc@justin.tv with any questions or suggestions.
Download
- Windows XP / Vista
- Linux
- Mac OSX
- Source
Installation
- Install or upgrade to VLC 1.0.1, released July 29, 2009. VLC 1.0.0 is missing codecs, and prior versions are unreliable.
- Download and unpack Jtvlc and follow the instructions below.
How to Use
Broadcasting is a simple, two-step process:
- Start VLC - When broadcasting, VLC should output a duplicate stream of the video and audio to any open port on your machine via the RTP protocol. You must also select the option to generate an sdp file at a specific location anywhere in your file system when setting up the stream.
- Start Jtvlc - Then, run Jtvlc via command line, passing in your justin.tv login, stream key, and the location of the sdp file. Your broadcast should be playing on your Justin.tv channel within a few seconds!
The instructions below show how to accomplish these steps!
Start VLC
The following examples show some of the many ways you can start streaming from VLC, and should be enough to get you started. If you're not already familiar with streaming via VLC, please see the VideoLan Streaming Howto Guide for detailed explanations on what each of these parameters do and for additional settings you can use (as well as how to do this via the VLC GUI): http://www.videolan.org/doc/streaming-howto/en/streaming-howto-en.html
Important Notes
In the following examples, when changing file locations to match your own, don't forget to also experiment with the vb= setting, which is your video bitrate in kbs. It can be set much higher than in the example depending on your internet connection, therefore providing a higher quality video for your viewers.
You can also reduce the resolution of the video using width=320,height=240 instead of using scale=1, but it's almost always better to reduce the bitrate setting.
Windows
The following examples were tested on Windows Vista
Ex. 1) To stream a video file:
"C:\Program Files (x86)\VideoLAN\VLC\vlc.exe" -vvv -I rc "file://C:\myfolder\myfile.mov" --sout="#transcode{venc=x264{keyint=60,idrint=2},vcodec=h264,vb=300,scale=1,acodec=mp4a,ab=32,channels=2,samplerate=22050}:rtp{dst=127.0.0.1,port=1234,sdp=file:///%HomeDrive%\%HomePath%\vlc.sdp}"
Ex. 2) To stream your webcam:
"C:\Program Files (x86)\VideoLAN\VLC\vlc.exe" dshow:// --sout="#transcode{venc=x264{keyint=60,idrint=2},vcodec=h264,vb=300,acodec=mp4a,ab=32,channels=2,samplerate=22050}:rtp{dst=127.0.0.1,port=1234,sdp=file:///%HomeDrive%\%HomePath%\vlc.sdp}"
Linux
Notes: Tested on Ubuntu 9.04
Ex. 1) To stream a video, displaying the original on your screen as it plays:
vlc "/home/joe/Documents/test.mov" -vvv input_stream --sout='#duplicate{dst=display, dst="transcode{venc=x264{keyint=60,idrint=2},vcodec=h264,vb=300,acodec=mp4a,ab=32,channels=2,samplerate=22050}:rtp{dst=127.0.0.1,port=1234,sdp=file:///home/joe/vlc.sdp}"}'
Ex. 2) To stream your webcam, also displaying it on your screen:
vlc v4l2:// -vvv input_stream --sout='#duplicate{dst=display, dst="transcode{venc=x264{keyint=60,idrint=2},vcodec=h264,vb=300,acodec=mp4a,ab=32,channels=2,samplerate=44100}:rtp{dst=127.0.0.1,port=1234,sdp=file:///home/joe/vlc.sdp}"}'
Mac OS X
Notes: Tested on Mac OSX 10.5.7
Ex. 1) To stream a video, displaying the original on your screen as it plays:
/Applications/VLC.app/Contents/MacOS/vlc "/Users/Bob/Desktop/video.mov" -vvv input_stream --sout='#duplicate{dst=display, dst="transcode{venc=x264{keyint=60,idrint=2},vcodec=h264,vb=300,acodec=mp4a,ab=32,channels=2,samplerate=22050}:rtp{dst=127.0.0.1,port=1234,sdp=file:///Users/Bob/Desktop/vlc.sdp}"}'
Ex. 2) To stream your iSight webcam (also displaying it on your screen):
/Applications/VLC.app/Contents/MacOS/vlc qtcapture:// -vvv input_stream --sout='#duplicate{dst=display, dst="transcode{venc=x264{keyint=60,idrint=2},vcodec=h264,vb=300,acodec=mp4a,ab=32,channels=2,samplerate=22050}:rtp{dst=127.0.0.1,port=1234,sdp=file:///Users/Bob/Desktop/vlc.sdp}"}'
Start Jtvlc
Once VLC is streaming, use the following command line format to start Jtvlc:
- jtvlc login stream_key sdp_file [-d]
- login: your username on Justin.tv
- stream_key: a unique value known only to you. You can find your stream key at the bottom of this page or via the Justin.tv REST API.
- sdp_file: this should be the same file path and name as given to VLC.
- -d (debug): the presence of the -d flag enables logging of debug information and output to the console.
Some examples:
Windows
jtvlc.exe bob3 live_gk423_cka141 file://c:/users/bob/desktop/vlc.sdp jtvlc.exe justin live_l0013_dlj3p1 c:/users/justin/desktop/vlc.sdp -d
Linux
jtvlc bob3 live_gk423_cka141 /home/bob/Desktop/vlc.sdp -d jtvlc justin live_l0013_dlj3p1 file:///home/justin/Desktop/vlc.sdp
Mac OS X
jtvlc.app/Contents/MacOS/jtvlc bob3 live_gk423_cka141 file:///Users/Bob/Desktop/vlc.sdp -d jtvlc.app/Contents/MacOS/jtvlc justin live_l0013_dlj3p1 /Users/Justin/Desktop/vlc.sdp
Troubleshooting
This section will attempt to point you in the right direction in case you have any questions.
VLC
Official Resources
- http://www.videolan.org
- irc chat: #videolan on freenode.net
Tips and Tricks
Add your tips and tricks here!
Jtvlc
Error Codes
- Finding your stream key (ERROR 100)
- Check that you are entering your correct username and its matching stream key. See 'Start Jtvlc' above for the web site to find your key.
- Forbidden (ERROR 101)
- The Justin.tv live video server could not be accessed for some reason. Simply try again.
- Could not find sdp file (ERROR 102)
- Check that VLC is actually generating the file by trying to open the file yourself. Check that you are passing the same file location to Jtvlc as you did to VLC.
- Empty sdp file (ERROR 103)
- You may need to restart Jtvlc (Ctrl + C) whenever you switch files and formats, switch from broadcasting on webcam to video, or similar in VLC.
- In general, you should restart Jtvlc whenever you restart VLC with changed settings.
Tips and Tricks
Add your tips and tricks here!
Feedback
- If you run into other errors or have any questions or feedback, please e-mail them to jtvlc@justin.tv. Thank you! Please contribute to this Justin.tv Community Wiki Page with your own VLC and Jtvlc tips and tricks.
Thanks
Developed by Vladislav Yazhbin. Thanks to Kyle Vogt and Dennis Jackson for testing and Mike Haimes and Arash Ferdowsi for other advice.
License
JTVLC is distributed under the terms of the MIT License.
Copyright (c) 2009 Justin.tv, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
