/
MP4LIVE_README.html
923 lines (896 loc) · 42.3 KB
/
MP4LIVE_README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>MP4LIVE README</title></head>
<body id="top">
<h1>MP4LIVE README</h1>
<p>
April, 2005<br>
Bill May<br>
Dave Mackie<br>
<p>
User Contributions by:
<br>
Dave Baker
Cesar Gonzalez
<P>
<b>
<a href="#mp4live">MP4LIVE</a><br>
<a href="#s1.3">Changes in Version 1.3</a><br>
<a href="#s1.1">Changes in Version 1.1</a><br>
<a href="#hw">Hardware Requirements</a><br>
<a href="#soft">Software Requirements</a><br>
<a href="#warning">Warnings</a><br>
<a href="#tips">Tips</a><br>
<a href="#build">Building and Installing</a><br>
<a href="#using">Using mp4live</a><br>
<a href="#href">Text and ISMA Href streams</a><br>
<a href="#qt">Use with QT 6.0 and Real One</a><br>
<a href="#nw">Network Transmission</a><br>
<a href="#dss">Use with Darwin Streaming Server</a><br>
<a href="#capture">Sharing Capture Cards</a><br>
<a href="#cli">Command Line Options</a><br>
<a href="#issues">Known Issues</a><br>
<a href="#unknown">Unknowns</a><br>
<a href="#links">Links</a><br>
<a href="#config">Configuration Variables</a><br>
</b>
<P>
<div id="mp4live">
<h2>MP4LIVE</h2>
</div>
<P>
MP4LIVE is a Linux audio/video capture utility that can capture and encode
audio and video in real-time. The results can be written to either an .mp4
file, transmitted onto the network via either unicast or multicast, or both
simultaneously! The audio is encoded with MP3 or AAC, and the video with
MPEG-4 Simple Profile.
<P>
Please use the MPEG4IP SourceForge site to report problems, suggest
enhancements, ask questions, etc. The URL is
<a href="http://www.sourceforge.net/projects/mpeg4ip">http://www.sourceforge.net/projects/mpeg4ip</a>
<P>
<b>Do not contact us via email</b>
<P>
<a href="#top">Back to top</a>
<p>
<div id="s1.3">
<h2>Changes in Version 1.3</h2>
</div>
<p>
Mp4live has been rewritten to handle multiple streams from
a single audio and video source, as well as being able to generate
ISMA href and text streams.
<p>
Added H.264 encoding through x264. Added b frame encoding for H.264 and
mpeg4 through ffmpeg.
<p>
lame and faac are no longer required; a G.711 encoder has been added
that will be the default.
<p>
If faac is installed, faac encoding will be the default encoding.
<P>
<div id="s1.1">
<h2>Changes in Version 1.1</h2>
</div>
<p>
Default mpeg4 encoder is no longer included with the package.
<p>
Add option to create new file name based on existing name when
recording files
<P>
Added mpeg2 video and mpeg1 layer 2 audio encoding with ffmpeg.
<p>
Added XVID 1.0 API code
<p>
Added decimate and deinterlace filters
<p>
<div id="hw">
<h2>Hardware Requirements</h2>
</div>
<p>
Note: most of this is outdated; I develop now on a dual-2GHz Pentium IV machine,
or a 3GHz machine with at least 512MB ram.
<P>
Pentium III class machine of at least 500 MHz
(Pentium IV class machine at 2 GHz is very nice.)
<P>
Note systems vary quite a bit in their video capture abilities. For instance,
I have a name brand 750 MHz PIII that drops frames when pushed to CIF sizes
at greater than 15 fps, but I have a no-name clone with a 800 MHz PIII that
can encode CIF @ 24 fps no problem.
<P>
RAM is not typically an issue. I develop on machines with 128 MB, but I believe much smaller configurations would work fine. The real issue is CPU speed.
We recommend at least 256Mb.
<P>
A sound card with an OSS compatible driver and capture ability, preferrably
at least 3.8.2 that have the SNDCTL_DSP_GETERROR define, and that support
the SNDCTRL_DSP_GETISPACE ioctl accurately.
<P>
A video device with a video4linux (v4l) compatible driver and memory mapped
capture ability. We also support (and recommend) the video4linux2 (v4l2) driver.
<P>
Known to work are:
<ul>
<li>
Video capture cards based on the Brooktree 8x8 chip
with an analog A/V source - VCR, DVD, Camcorder, Settop box, Tivo, etc.
Typically a video capture card will support composite video inputs.
Some will also have S-Video input.
Others will also have a TV Tuner input.
</li>
<li>
Logitech Quickcam Express Webcam (sometimes)
</li>
</ul>
<P>
Note on multi-processor machines (SMP): mp4live is multithreaded at a coarse
level. Specifically the video encoder, audio encoder, file recorder, network
transmitter, and user interface each have their own thread. Unfortunately for
owners of multiprocessor machines, the video encoder thread dominates the
computational requirements so one CPU will be very busy, and the others will
be lightly to moderately loaded. For those looking for a project, a multi-
threaded video encoder would certainly provide an interesting challenge.
<p>
Again - a bit out-dated; if you're doing multiple encodings, this is no
longer true.
<P>
<a href="#top">Back to top</a>
<P>
<div id="soft">
<h2>Software Requirements</h2>
</div>
<P>
Linux with a 2.4 or later kernel.<br>
We recommend a kernel with V4L2 built in. See the instructions on
<a href="Building_mpeg4ip_with_V4L2_support.html">building it yourself</a>
<P>
The 2.6 kernel should have the correct V4L2 interface.
<p>
Drivers for sound and video devices
<P>
bttv 0.7 or later video capture driver
(Included with RedHat 7.1 and later)
(0.9 required for v4l2)<br>
qce webcam driver
<P>
<a href="#top">Back to top</a>
<P>
<div id="warning">
<h2>WARNINGS!</h2>
</div>
<P>
Please see the MPEG4IP README regarding legal issues, and the list of
open source packages that are redistributed with this code.
<P>
This is a LINUX program! Do not even think about trying to get this to
run on Windows! Even moving it to other UNIX systems would require some
re-programming since the sound and video capture interfaces are Linux
specific.
<p>
We no longer include a mpeg-4 encoder native with the package. You will
have to download ffmpeg or xvid if you want to encode with mpeg-4. You
will also want to include a good audio encoder, like faac, lame or twolame.
See the main readme for more information.
<P>
By far the easiest route is to use a Linux distribution that already has a
2.6 kernel and the bttv driver, and the associated i2c module built into it.
<p>
See the <a href="Building_mpeg4ip_with_V4L2_support.html">instructions</a> on
how to build your own kernel with V4L2 included.
<P>
I've had many headaches with sound cards under Linux. Before you start using
mp4live, please make sure you're able to playback and record with your sound
card!
<P>
You should definitely increase the number of capture buffers for the bttv
driver. This reduces the chance of dropping video frames due to transient
delays in the system. By default bttv uses 2 buffers. You can increase this
by editting /etc/modules.conf and adding the line
"add options bttv gbuffers=32"
at the end of the file. The value 32 is my recommendation but you can
experiment with other values if you are so inclined.
<br>Note: with v4l2, we're not sure if this is required any more.
<P>
<a href="#top">Back to top</a>
<P>
<div id="tips">
<h2>Tips</h2>
</div>
<P>
I suggest you disable any fancy, computationally intensive screensavers
when using mp4live to capture long programs. Along the same lines, don't
run any programs that make large resource demands (CPU, bus, disk, network)
while mp4live is running.
<P>
If you're capturing large video image sizes, then you may be able to boost
the encoded video frame rate by disabling video preview. In general, once
you've got the system working, disabling preview is a good idea.
<P>
The AAC audio encoder is somewhat slower than the MP3 audio encoder so
you may see lower video frame rates and greater sensitivity to CPU load
if you are using AAC. (2004 note - not so much any more).
<P>
Linux supports the POSIX soft real-time extensions and mp4live will attempt
to use these to give it priority over non-real time processes. Typically
these calls can only be made by processes with root privileges, so you may
want to run mp4live as root for this reason.
<P>
If you have the latest version of OSS, you have a chance of detecting
audio overruns. That, in combination with the latest version and
working on a fast machine will give fairly good lip syncronization up to
about the hour mark running 90% of the CPU with V4L. With V4L2, we've
had good audio and video sync out beyond 500 hours in our lab.
<h3>BTTV Audio</h3>
<P>
<i>contributed by Dave Baker.</i>
<p>
The bt878 cards (WinTV PCI and family) are not entirely straightforward to
capture audio from, and there are a couple of different ways:
<p>
<h4>Capturing using the TV card</h4>
<p>
The WinTV PCI in particular has an on-board audio device that can be used to
capture audio. Simply load the btaudio (or snd-bt87x for ALSA). Beware that
if you have a sound card then the WinTV's device will probably have been
allocated /dev/dsp1, so you will have to set mp4live to capture from this.
It will also have /dev/dsp2, as it registers an analog and digital device -
see your /var/log/messages file. Try the digital one first. Not all bt878
boards have this audio device and not all of them have them wired the same,
so this may or may not work. Note especially that the WinTV PCI (and possibly
others) are able to capture from the tuner using this but will not capture
audio from the 3.5mm jack input on the card.
<p>
<h4>Capturing using a separate sound card</h4>
<p>
The WinTV cards have two 3.5mm jacks on the back - one input and one output.
As mentioned above, the WinTV PCI cannot use the input to record sound itself
(other cards may be able to). The idea is that when the card is capturing
video from the tuner, the card feeds the tuner's audio out of the output jack,
but when it is capturing from the composite or S-Video connectors, it connects
the input and output together. Hence, if you'll only ever be capturing from
composite and/or S-Video, you may as well connect your audio source directly
into the line-in jack on your sound card. Either way, if you want to capture
audio that isn't coming from the tuner, you'll need to use a separate sound
card.
<p>
It is also worth noting that the quality of the sound card used will have a
big effect on the lip sync of your captured video. Cheaper sound chips like
the ones commonly found on mainboards as on-board audio can have very poor
clocks, which causes the audio and video to drift out of sync, often making a
noticable lag over only five or ten minutes. Use a proper sound card!
<p><i>Editor's note - mp4live should compensate for this correctly, if the V4L2
video interface is used, and the sound card correctly returns the value from
the SNDCTL_DSP_GETISPACE.</i>
<p>
<a href="#top">Back to top</a>
<P>
<div id="build">
<h2>Building and Installing</h2>
</div>
<P>
See the MPEG4IP README for general notes about the build environment.
<P>
Assuming you've already done a build at the top level of mpeg4ip, and
you're on a Linux system then mp4live should be built and waiting for you
in this directory. If you've done a top level 'make install', the mp4live
will be installed into '/usr/local/bin'. Of course, you can also issue
'make' and 'make install' from this directory as well.
<P>
<a href="#top">Back to top</a>
<P>
<div id="using">
<h2>Using mp4live</h2>
</div>
<p>
Typically, there is no need for command line options to mp4live. You can
just type 'mp4live' and you'll be up and running.
<P>
Global configuration settings are stored in your home directory in ~/.mp4live_rc.
This file is read when mp4live is started.
<p>
A concept that is new for mp4live in 1.3 are the concepts of profiles and
streams. A profile can be used to name a set of audio, video, or text
parameters. Different profiles can be created, and can be selected from
at any time mp4live is run. For example, you could create a video profile
that has mpeg-4 with ffmpeg at 320x240, 500Mbps, and another one with mpeg-4
with xvid at 352x288, 750Mbps. You can then switch between these 2
profiles without changing each setting.
<p>
Profiles are stored in a user settable directory (by default ~/.mp4live_d),
with Audio, Video and Text sub-directories. Profiles can be created
with mp4live (use the drop-down menu and select "Add"), or changed (select
the profile, then select "Customize"). It is recommended that the
profile directory not change; for multiple instances of mp4live, use
seperate stream directories.
<P>
A stream is an group of a single audio, video, and/or text profiles. A
stream can be transmitted, recorded or both.
<p>
Mp4live can support as many streams as your CPU processing power can
support. Each stream has the same source, but can have different
destination parameters.
<p>
Mp4Live is smart in creating the streams; for any given audio, video or
text profile, the encoding specified by that profile will be done only
1 time, no matter how many streams include that profile.
<p>
mp4live will capture video at the largest size specified in the
profiles, and will capture audio at the highest sample rate. Video
for other profiles is resized; audio is resampled and converted from
stereo to mono, if needed.
<p>
By creating multiple streams, different combinations of audio and
video profiles can be used and saved. For example
<ul>
<li>different streams with different profiles can be used; each profile is
only encoded and transmitted over a single multicast address if the
default settings are used.</li>
<li>different streams can be used with the same profiles to transmit to different
destinations; only the ip packets will be duplicated </li>
<li>Audio only streams can be created from audio/video streams by duplicating
the stream and disabling video on 1 of the streams. SDP files, and
mp4 files will be created as specified.</li>
</ul>
<p>
The default settings for mp4live are to record 1 minute of audio and video
to an mp4 file, ./capture.mp4 The first time you use the program, it's
a good idea to just hit the Start button, and see what happens. If all
goes well, 1 minute later you have a playable/streamable mp4 file. If you
don't get this, then it's time to review this README, and it that doesn't
help, then fire off a message on the MPEG4IP SourceForge discussion group.
<P>
<P>
Assuming things are working you can now use the various controls to adjust
things like the video size and frame rate, the audio sampling rate, the
encoded bitrates, etc. The UI is hopefully self-explanatory. If not, let us
know what's confusing and we'll look at fixing that. (I'm a big believer that
if you need to read a document to use a UI, then the UI is broken and should
be fixed. Of course, as I've re-learned many times, what is obvious and natural
to me, isn't always to other people.)
<P>
If you're capturing video that uses "widescreen" or "letterbox" format,
it's a big win to change the "Aspect Ratio" in the Video Settings. This
will cause the video to be automatically cropped so you don't waste precious
CPU time encoding the empty black bars at the top and bottom of the screen.
<P>
The capture cards will always try to capture frame rates based on what
the setting of the video card is (either NTSC or PAL).
<P>
The default is to assume that the video driver is going to capture close
to the correct frame rate of 29.97 for NTSC, 25 for PAL. If you don't
think that this is working quite right, try the "videoTimestampCache=0"
to the .mp4live_rc before you start. (This may be the case with usb
web cams, but most likely not regular capture cards). Note: this is
for v4l users only.
<p>
A user contributed some simple video filters. We have a decimate
filter (which captures video at 2 times the resolution, and scales it
back down), and a deinterlace filter (which will do a linear blend style
of deinterlace on the Y plane before encoding).
<p>
The decimate filter is used on the source, while the deinterlace filter
is done on a per-profile basis.
<p>
These filters do take up some processing power, so be careful.
<P>
<a href="#top">Back to top</a>
<P>
<div id="href">
<h2>Use with Text or ISMA Href Streams</h2>
</div>
<p>
Along with audio and video, mp4live allows you to transmit plain
text, or href streams as defined in ISMA's 2.0 specification.
<p>
There are currently 3 sources of getting entries for these streams:
<ol>
<li>
Entry GUI - allows the user to enter entries in a dialog
</li>
<li>
Timed File - a file with time in seconds, followed by element to send:<br>
0 http://www.cisco.com<br>
2.5 http://www.yahoo.com<br>
3.5 http://www.google.com<br>
</li>
<li>
File with Entry GUI - specify entries in a file, then use a GUI. The user can
control when the entry is sent, as well as navigating through the entries, or
entering an entry not in the file.
</li>
</ol>
<p>
ISMA Href's can be used to either automatically open a URL (also
known as auto dispatch), or open the target URL when clicked.
<p>
Hrefs have the following format:
<p>
[A]<entry url>[T<target element>][E<embeded parameters element>][M<>]
<br>
The < and > are mandatory around the entry URL. The remain elements
defined as:
<ul>
<li>A is used to indicate auto-dispatched urls; if missing url is clickable</li>
<li>T<target> is used to specify a target for the URL (frames, etc)</li>
<li>E<embed> is used for extra parameters (unused now)</li>
<li>M<> is used with clickable url to get click location<li>
</ul>
<p>
mp4live will automatically generate the A< and > if a < is not
the first character entered. So if <code>http://www.cisco.com</code> is
entered, <code>A<http://www.cisco.com></code> will be generated.
<p>
<a href="#top">Back to top</a>
<p>
<div id="qt">
<h2>Use with QT 6.0 and Real One</h2>
</div>
<P>
It is possible to create content for QT 6.0 and Real One with the
Envivio plug in. You must create with the audio encoding set to
AAC for both of these.
<p>
Quicktime does not seem to like 7350Hz Sampling frequency; do not use
this if you want interoperability with Quicktime.
<P>
If you want to stream (using the instructions below), you must have
Envivio version 1.2. Download Real One, then download Envivio TV
version 1.2 afterwards. The Envivio plugin downloaded with Real One
will not play multiple AAC frames in a RTP packet, so your sound will
appear to stutter.
<P>
If you want to stream mpeg2 to the QT player (with the mpeg2 add-on), you
will need to broadcast MPEG2 video and MPEG layer 2 audio. For both of
these, ffmpeg is required. Make sure to use the rtpUseMp3RtpPayload14=1
configuration setting.
<p>
September, 2005 note: it appears that Quicktime 7.0 will allow streaming
of various codecs; I was able to get mpeg-4 video in conjunction with
G.711. You can try various codecs yourself.
<p>
<a href="#top">Back to top</a>
<P>
<div id="nw">
<h2>Network Transmission</h2>
</div>
<P>
To use mp4live to transmit live audio/video to the network, follow these
directions:
<P>
Select the Transmit check box in the Stream Information section of the
main window.
<P>
By default, mp4live will generate multicast address so that there are
no overlaps. The "Edit->Generate Addresses" menu item will pick new,
random addresses. Each stream that has a common profile will transmit
on the same address:port.
<P>
If you wish to change this, select the 'Set Address' button for the
stream you wish to change. A dialog will appear that allows the
choice between Generated Addresses or Fixed address. To transmit to a
unicast address, use the Fixed Address setting.
<P>
When you press mp4live's 'Start' button, media transmission to the network
will begin. Also a small text file with extension .sdp will be created that
describes the media transmission for the player. The player needs the .sdp
file to be able to tune into the media streams. The sdp files are generated
pretty much any time a configuration item is changed; they can also be
generated by using "Edit->Generate SDP Files" menu item, or using the
command line argument.
<p>
SDP file names will by default contain the stream name, with spaces converted
to underlines.
<P>
The most convenient way to distribute the .sdp file is to have mp4live write
it to a directory that is accessible from a web server (httpd) that is running
on the same machine as mp4live. This allows the client to be started with
the HTTP URL of the sdp file, and it will download the .sdp file via http
and then use the information in the .sdp file to tune into the network
transmission. E.g.: <P><samp>gmp4player http://myserver/myprogram.sdp</samp>
<P>
For Real One, use the Open command with http://myserver/myprogram.sdp. For
QT6.0, use Open URL.
<P>
You can of course distribute the .sdp file in a number of other ways, say
ftp, or email. You would then start the player with the local file name
of the sdp file, e.g.:
<P><samp>gmp4player myprogram.sdp</samp>
<P>
<a href="#top">Back to top</a>
<P>
<div id="dss">
<h2>Use with Darwin Streaming Server</h2>
</div>
<P>
If you would like to use mp4live in conjunction with the Darwin Streaming
Server (DSS), that is easy to do. You can have mp4live both record and
transmit live media streams. When you record the .mp4 files, just ensure
that they are written to the media directory that is accessible via the Darwin
Streaming Server, typically /usr/local/movies. Once the recording is complete,
it will be available for on-demand playback.
<P>
For example:
<P><samp>gmp4player rtsp://DSS/mymovie.mp4</samp>
<P>
The Darwin Streaming Server can also be configured to act as a relay agent
for the mp4live media streams. Copy the .sdp file generated by mp4live to
the media directory of the Darwin Streaming Server (e.g. /usr/local/movies)
Players can now request the .sdp file from DSS which will cause DSS to act
as a relay between mp4live and the player.
<P>
For example:
<P><samp> gmp4player rtsp://DSS/mymovie.sdp</samp>
<P>
If you're having problems where gmp4player is stopping after 2 minutes when
relaying through a Darwin Streaming Server, add the line <code>rtpNoBRR0=1</code>
to your .mp4live_rc. Darwin is expecting RTCP messages from gmp4player, and the b=RR:0 statement
in the SDP stops gmp4player from sending them.
<P>
<a href="#top">Back to top</a>
<P>
<div id="capture">
<h2>Sharing Capture Cards</h2>
</div>
<P>
If you have another program that wants to simultaneously process the raw
audio and/or video from the capture cards, there is typically a problem
in that many drivers only support one reader at a time. To address this
issue, mp4live can be configure to write the raw audio and/or video that
it reads from the capture cards to a named pipe (fifo). A named pipe looks
like a file, but the data only exists in memory and never goes to disk.
This is an efficient way to have the two applications share the media data.
<P>
To configure this feaure, add the following to ~/.mp4live_rc (or whatever
configuration file you want to use), changing "/dir" to some directory
where you want the named pipes to exist:
<P>
rawEnable=1<br>
rawAudioFile=/dir/audio_pipe<br>
rawAudioUseFifo=1 <br>
rawVideoFile=/dir/video_pipe<br>
rawVideoUseFifo=1 <br>
<P>
The audio format is 16 bit PCM, the video format is YUV12 (planar 4:2:0 YUV).
<P>
<a href="#top">Back to top</a>
<P>
<P>
<div id="cli">
<h2>Command Line Options</h2>
</div>
<P>
There are currently four command line options to mp4live:<br>
<code>
--file <config-file><br>
--automatic<br>
--headless<br>
--sdp<br>
--config-vars<br>
</code>
<P>
<code>--file <config-file></code> allows specification of the mp4live configuration file
to something other than ~/.mp4live_rc. Perhaps you have a several frequently
used configurations. You can save the configuration settings to different
files, and then use this option to choose among them.
<P>
<code>--automatic</code> causes mp4live to act as if the Start button was pressed
immediately upon startup. The program will do whatever the current
configuration instructs it to do. This option can be used in conjunction
with the 'cron' utlity to do scheduled recording and/or transmission.
<P>
<code>--headless</code> causes mp4live to behave in the <code>--automatic</code> mode AND not display any user interface.
<P>
<code>--sdp</code> causes mp4live to just generate the sdp file based on its configuration file and then exit.
<p>
<code>--config-vars</code> will cause mp4live to display the list of all
possible configuration variables and exit.
<p>
In addition, any of the configuration variables can be overwritten by
using --<variable>=<value>. Make sure that the case of
variable matches the case from the --config-vars display.
<p>
<P>
<a href="#top">Back to top</a>
<P>
<div id="issues">
<h2>Known Issues</h2>
</div>
<P>
Using a system with a PCI instead of an AGP video display card can cause
video "tearing" with CIF or larger size images. I.e. the PCI bus quickly
gets swamped moving raw video from the video capture card to the CPU, and
then from the CPU to the video display card. Having the AGP bus for the
CPU to video display card transfer alleviates this problem. If someone is
interested one could experiment with the video overlay capabilities of the
Bt8x8 to bypass this problem, but it would require some rework of our code
with respect to the video preview function.
<P>
It took me awhile to figure this out so perhaps I can save some of you some
time. If you use the Hauppage WinTV Go card you need to connect the mini-jack
on the card to the line-in input on your sound card in order to get the
audio signal from the TV tuner.
<P>
Note there is currently no support for DV/mini-DV camcorders via FireWire.
You can of course still use these via their composite or S-Video outputs.
<P>
More recent versions of mp4live add streaming hint tracks as a post-processing
step (i.e. after the recording is finished). For long duration recording
(1 hour or greater), this step can take a minute or two. I'm hoping to
enhance the UI to provide user feedback while this is taking place, but
for now the application gets very unresponsive during this period. If this
is a big problem for you, there is a configuration option to disable the
hinting process, "recordMp4HintTracks=0". The mp4 file can always be hinted
later with the mp4creator utility.
<P>
The audio and video should be in sync if you're using the latest tools
(V4L2 and the latest OSS driver). If you're not, you will have problems
in long term (usually an hour or so).
<P>
The current audio/video synchronization algorithm in the MP4 File Recorder
starts by dropping video frames until an audio frame is loaded. It then
drops subsequent video frames until the next I video frame is loaded.
This I frame is stretched to the beginning of the first audio frame to
synchronize the video and audio.
Because of this, the first video frame is displayed for a longer duration
before the video starts rolling. This duration is usually of the order of
4 or 5 video frame times and generally unnoticable.
<br>
We've done our best to try to start the audio first, but since the video
is already running in the preview (if turned on), the file recorder receives
a bunch of video frames before the first audio frame propagates to the
file recorder. Given this, the above algorithm seems to be a resonable
solution.
<p>
Sometimes, you may experience a crash while changing the video parameters such
as height/width or aspect ratio. If this occurs, change the
<a href="#vheight">parameter </a> in your .mp4live_rc file, and restart
mp4live, or just pass the videoRawWidth and videoRawHeight as command
line parameters.
<P>
H.261 recording does not work
<p>
<a href="#top">Back to top</a>
<P>
<div id="unknown">
<h2>Unknowns</h2>
</div>
<P>
I've only used mp4live with two video capture cards the Viewcast Osprey 100
and the Hauppage WinTV Go. There are many other Bt8x8 based capture cards
listed in the bttv driver documentation. Odds are you're using one of these ;-)
Reports from initial users suggest though that the bttv driver handles the
wide variety of cards gracefully, and mp4live doesn't have card specific
issues.
<P>
If you do have problems with mp4live, my first suggestion is that you download
the latest version of the xawtv package, and try it with your capture card.
If it works and mp4live doesn't then I'd be glad to hear from you. If xawtv
doesn't work with your capture card, then I can't help you. Something is
wrong with your capture card/system/bttv driver/kernel combination. I don't
have the capability or inclination to debug that for you!
<p>
<a href="#top">Back to top</a>
<P>
<div id="links">
<h2>Links</h2>
</div>
<P>
<table summary="links">
<tr>
<td>MPEG4IP</td>
<td><a href="http://www.mpeg4ip.net/">http://www.mpeg4ip.net/</a></td>
</tr>
<tr>
<td>bttv driver</td>
<td><a href="http://bytesex.org/bttv/">http://bytesex.org/bttv/</a></td>
</tr>
<tr>
<td>qce driver</td>
<td><a href="http://www.sourceforge.net/projects/qce-ga">http://www.sourceforge.net/projects/qce-ga</a></td>
</tr>
<tr>
<td>xawtv</td>
<td><a href="http://bytesex.org/xawtv/">http://bytesex.org/xawtv/</a></td>
</tr>
<tr>
<td>Xvid</td>
<td><a href="http://www.xvid.org/">http://www.xvid.org/</a></td>
</tr>
<tr>
<td>LAME</td>
<td><a href="http://www.sourceforge.net/projects/lame">http://www.sourceforge.net/projects/lame</a></td>
</tr>
<tr>
<td>TWOLAME</td>
<td><a href="http://www.twolame.org">http://www.twolame.org</a></td>
</tr>
<tr>
<td>FAAC</td>
<td><a href="http://www.audiocoding.com">http://www.audiocoding.com</a></td>
</tr>
<tr>
<td>FFMPEG</td>
<td><a href="http://ffmpeg.sourceforge.net">http://ffmpeg.sourceforge.net</a></td>
</tr>
</table>
<P>
<a href="#top">Back to top</a>
<P>
<div id="config">
<h2>Configuration Variables</h2>
</div>
<h3>Global Configuration</h3>
<p>Global configuration variables are stored in .mp4live_rc file
<P>
<table border cellpadding=4 summary="Global Configuration variables">
<tbody>
<tr><th colspan=5 align=center><b>Application Level</b></th></tr></tbody>
<tbody>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Does</th></tr>
<tr align=center>
<td>useRealTimeScheduler</td><td>bool</td><td>true</td><td>attempts to use real time features of the OS<br>Probably only suceeds as root</td></tr>
<tr align=center><td>duration</td><td>int</td><td>1</td><td>duration in durationUnits</td></tr>
<tr align=center><td>durationUnits</td><td>int</td><td>60</td><td>Number of seconds per duration unit (1, 60, 3600, 86400)</td></tr>
<tr align=center><td>debug</td><td>bool</td><td>false</td><td>Enable debug output</td></tr>
<tr align=center><td>signalHalt</td><td>string</td><td>sighup</td><td>Signal used in no gui mode to stop</td></tr>
<tr><th colspan=5 align=center><b>Global Audio Settings</b></th></tr>
<tr align=center><td>audioSourceType</td><td>string</td><td>OSS</td><td>Audio Source Type (only OSS for now)</td></tr>
<tr align=center><td>audioDevice</td><td>string</td><td>/dev/dsp</td><td>Audio Device to use</td></tr>
<tr align=center><td>audioMixer</td><td>string</td><td>/dev/mixer</td><td>Audio Mixer to use</td></tr>
<tr align=center><td>audioInput</td><td>string</td><td>mix</td><td>Audio Input Type to use</td></tr>
<tr align=center><td>audioOssUseSmallFrags</td><td>bool</td><td>true</td><td>Enable small fragments size in OSS</tr>
<tr align=center><td>audioOssFragments</td><td>int</td><td>128</td><td>Number of fragments</tr>
<tr align=center><td>audioOssFragSize</td><td>int</td><td>8</td><td>Size of fragments</tr>
<tr><th colspan=5 align=center><b>Global Video Settings</b></th></tr>
<tr align=center><td>videoSourceType</td><td>string</td><td>V4L</td><td>Video Source to use <br>(V4L is for both V4L and V4L2)</tr>
<tr align=center><td>videoDevice</td><td>string</td><td>/dev/video0</td><td>Video Device to use</tr>
<tr align=center><td>videoInput</td><td>int</td><td>1</td><td>Video Input to use (index from V4L)</tr>
<tr align=center><td>videoSignal</td><td>int</td><td>1</td><td>PAL-0, NTSC-1, SECAM-2</tr>
<tr align=center><td>videoTuner</td><td>int</td><td>-1</td><td>Which tuner to use - usually 0</td></tr>
<tr align=center><td>videoChannelListIndex</td><td>int</td><td>0</td><td>Which channel list to use for tuner<br>see video_util_tv.cpp</tr>
<tr align=center><td>videoChannelIndex</td><td>int</td><td>1</td><td>0 based index for channel in above list</tr>
<tr align=center><td>videoPreview</td><td>bool</td><td>true</td><td>Show Video Preview in Gui</tr>
<tr align=center><td>videoRawPreview</td><td>bool</td><td>false</td><td>Show Raw Video Preview in Gui</tr>
<tr align=center><td>videoEncodedPreview</td><td>bool</td><td>true</td><td>Show Encoded Video Preview in Gui</tr>
<tr align=center><td>videoBrightness</td><td>int</td><td>50</td><td>Brightness level (0 to 100)</tr>
<tr align=center><td>videoHue</td><td>int</td><td>50</td><td>Hue level (0 to 100)</tr>
<tr align=center><td>videoColor</td><td>int</td><td>50</td><td>Color level (0 to 100)</tr>
<tr align=center><td>videoContrast</td><td>int</td><td>50</td><td>Contrast level (0 to 100)</tr>
<tr align=center><td>videoTimestampCache</td><td>bool</td><td>true</td><td>Calculate timestamps, rather than read with timestamp<br>(V4L only)</tr>
<tr align=center><td>videoFilter</td><td>string</td><td>none</td><td>Video filter to use (none, "deinterlace - blend")</td></tr>
<tr><th colspan=5 align=center><b>Global Recording Options</b></tr>
<tr align=center><td>recordEnable</td><td>bool</td><td>true</td><td>True to record</tr>
<tr align=center><td>recordRawInMp4</td><td>bool</td><td>true</td><td>True to record raw audio and video in MP4 File</tr>
<tr align=center><td>recordRawMp4Audio</td><td>bool</td><td>false</td><td>True to record raw audio <br>(PCM at encode frequency)</tr>
<tr align=center><td>recordRawMp4Video</td><td>bool</td><td>false</td><td>True to record raw video <br>(YUV at height/width)</tr>
<tr align=center><td>recordMp4HintTracks</td><td>bool</td><td>true</td><td>Record hint tracks when recording completed</tr>
<tr align=center><td>recordMp4Optimize</td><td>bool</td><td>false</td><td>Optimize mp4 file when recording completed</tr>
<tr align=center><td>recordMp4FileStatus</td><td>integer</td><td>1</td><td>What happens to file when restarted:<br>
0 - append, 1 - overwrite,<br> 2 - create new file with timestamp</tr>
<tr align=center><td>rawEnable</td><td>bool</td><td>0</td><td>ouput raw audio/video to file</tr>
<tr align=center><td>rawAudioUseFifo</td><td>bool</td><td>0</td><td>Output to pipe (see Sharing Capture Cards)</tr>
<tr align=center><td>rawAudioFile</td><td>String</td><td>capture.yuv</td><td>File to store raw PCM</tr>
<tr align=center><td>rawVideoUseFifo</td><td>bool</td><td>0</td><td>Output to pipe (see Sharing Capture Cards)</tr>
<tr align=center><td>rawVideoFile</td><td>String</td><td>capture.yuv</td><td>File to store raw YUV</tr>
<tr><th colspan=5 align=center><b>Global Transmission (RTP) Options</b></tr>
<tr align=center><td>rtpPayloadSize</td><td>int</td><td>1460</td><td>max bytes of audio or video per packet</tr>
<tr align=center><td>rtpMulticastTtl</td><td>int</td><td>15</td><td>Multicast TTl</tr>
<tr align=center><td>rtpDisableTimestampOffset</td><td>bool</td><td>false</td><td>If true, start RTP timestamps at 0<br>if false, start at random offset</tr>
<tr align=center><td>rtpUseSingleSourceMulticast</td><td>bool</td><td>false</td><td>Use SSM multicast</tr>
<tr align=center><td>rtpNoBRR0</td><td>bool</td><td>false</td><td>If true, do not include b=RR:0 in SDP</tr>
</tbody>
</table>
<h3>Stream Configuration</h3>
<p>Stream configuration variables are stored in an individual file per
stream in the .mp4live_d/Stream directory.
<P>
<table border cellpadding=4 summary="Stream Configuration">
<tbody>
<tr><th colspan=5 align=center><b>Stream Configuration</b></tr></tbody>
<tbody>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Does</th></tr>
<tr align=center><td>name</td><td>string</td><td>none</td><td>Mandatory Name</td></tr>
<tr align=center><td>audioEnabled</td><td>bool</td><td>true</td><td>True if audio is enabled</td></tr>
<tr align=center><td>videoEnabled</td><td>bool</td><td>true</td><td>Enable Video</tr>
<tr align=center><td>textEnabled</td><td>bool</td><td>true</td><td>Enable Text</tr>
<tr align=center><td>recordEnabled</td><td>bool</td><td>false</td><td>True to record</tr>
<tr align=center><td>recordFile</td><td>string</td><td><stream name>.mp4</td><td>MP4 Filename to create</tr>
<tr align=center><td>transmitEnabled</td><td>bool</td><td>true</td><td>True to transmit over the network</tr>
<tr align=center><td>sdpFile</td><td>string</td><td><stream name>.sdp</td><td>Where to store sdp file describing session</tr>
<tr align=center><td>audioAddrFixed</td><td>bool</td><td>false</td><td>true to fix address; false autogenerates</tr>
<tr align=center><td>audioDestAddress</td><td>string</td><td>224.1.2.3</td><td>Audio Stream destination address</tr>
<tr align=center><td>audioDestPort</td><td>int</td><td>20002</td><td>Audio Stream destination port</tr>
<tr align=center><td>videoAddrFixed</td><td>bool</td><td>false</td><td>true to fix address; false autogenerates</tr>
<tr align=center><td>videoDestAddress</td><td>string</td><td>224.1.2.3</td><td>Video Stream destination address</tr>
<tr align=center><td>videoDestPort</td><td>int</td><td>20000</td><td>Video Stream destination port</tr>
<tr align=center><td>textAddrFixed</td><td>bool</td><td>false</td><td>true to fix address; false autogenerates</tr>
<tr align=center><td>textDestAddress</td><td>string</td><td>224.1.2.3</td><td>Text Stream destination address</tr>
<tr align=center><td>textDestPort</td><td>int</td><td>20004</td><td>Text Stream destination port</tr>
</tbody>
</table>
<h3>Audio Profile</h3>
<p>Audio profile configuration variables are stored in an individual file per
stream in the .mp4live_d/Audio directory.
<P>
<table border cellpadding=4 summary="Audio Profiles">
<tbody>
<tr><th colspan=5 align=center><b>Audio Profile Settings</b></tr></tbody>
<tbody>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Does</th></tr>
<tr align=center><td>name</td><td>string</td><td>none</td><td>Mandatory Name</td></tr>
<tr align=center><td>audioChannels</td><td>int</td><td>2</td><td>Number of Encoded Audio Channels (1 or 2)</td></tr>
<tr align=center><td>audioSampleRate</td><td>int</td><td>44100</td><td>Audio Frequency Sample Rate</td></tr>
<tr align=center><td>audioBitRateBps</td><td>int</td><td>128000</td><td>Encoded Audio Bit Rate</td></tr>
<tr align=center><td>audioEncoding</td><td>string</td><td>MP3</td><td>Audio Encoding to use</tr>
<tr align=center><td>audioEncoder</td><td>string</td><td>LAME</td><td>Audio Encoder to use</tr>
<tr align=center><td>rtpUseMp3RtpPayload14</td><td>bool</td><td>false</td><td>if true, use RTP payload 14 and 90000 timescale<br>if false, use dynamic payload and frequency timescale</tr>
<tr align=center><td>rtpMaxFramesPerPacket</td><td>int</td><td>0</td><td>if non-zero, set maximum number of frames per packet</tr>
</tbody>
</table>
<h3>Video Profile</h3>
<p>Video profile configuration variables are stored in an individual file per
stream in the .mp4live_d/Video directory.
<P>
<table border cellpadding=4 summary="Video Profiles">
<tbody>
<tr><th colspan=5 align=center><b>Video Profile Settings</b></tr></tbody>
<tbody>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Does</th></tr>
<tr align=center><td>name</td><td>string</td><td>none</td><td>Mandatory Name</td></tr>
<tr align=center><td>videoEncoder</td><td>string</td><td>xvid</td><td>Video Encoder Type</tr>
<tr align=center><td>videoEncoding</td><td>string</td><td>MPEG4</td><td>Video Encoding Type</tr>
<tr align=center><td id="vheight">videoWidth</td><td>int</td><td>320</td><td>Width of output frame in pixels</tr>
<tr align=center><td>videoHeight</td><td>int</td><td>240</td><td>Height of output frame in pixels</tr>
<tr align=center><td>videoCropAspectRatio</td><td>float</td><td>1.33</td><td>Aspect ratio</tr>
<tr align=center><td>videoFrameRate</td><td>float</td><td>29.97</td><td>Frame Rate</tr>
<tr align=center><td>videoKeyFrameInterval</td><td>float</td><td>2.0</td><td>Number of Seconds between Key Frames</tr>
<tr align=center><td>videoBitRate</td><td>int</td><td>500</td><td>Encoded Video Bit Rate in 1000 bits per second</tr>
<tr align=center><td>videoForceProfileId</td><td>bool</td><td>false</td><td>True to force MPEG4 Video Profile to videoProfileId</tr>
<tr align=center><td>videoProfileId</td><td>int</td><td>3 (SP@L3)</td><td>MPEG4 Video Profile when forcing</tr>
<tr align=center><td>videoH261Quality</td><td>int</td><td>10</td><td>Starting H.261 Video Quality</tr>
<tr align=center><td>videoH261QualityAdjFrames</td><td>int</td><td>8</td><td>Number of frames to adjust H.261 Quality over</tr>
<tr align=center><td>videoCaptureBuffersCount</td><td>int</td><td>16</td><td>Number of capture buffers to request<br>(V4L2 only)</tr>
<tr align=center><td>videoFilter</td><td>string</td><td>none</td><td>Video filter to use (none, "deinterlace - blend")</td></tr>
<tr align=center><td>videoUseBFrames</td><td>bool</td><td>0</td><td>Encode using b-frames (ffmpeg, x264 encoders only</td>
<tr align=center><td>videoBFrameNum</td><td>int</td><td>2</td><td>Number of b frames (ffmpeg, x264 encoders only</td>
<tr><th colspan=5 align=center><b>Mpeg-4 Video Options</b></tr>
<tr align=center><td>videoMpeg4ParWidth</td><td>int</td><td>0</td><td>Mpeg-4 par width value</td>
<tr align=center><td>videoMpeg4ParHeight</td><td>int</td><td>0</td><td>Mpeg-4 par height value</td>
<tr><th colspan=5 align=center><b>XVID 1.0 Video Options</b></tr>
<tr align=center><td>xvid10VideoQuality</td><td>int</td><td>6</td><td>Video Quality (0 to 6 values)</td>
<tr align=center><td>xvid10UseGMC</td><td>bool</td><td>false</td><td>Use GMC (do not use if using Quicktime Clients</td>
<tr align=center><td>xvid10UseQpel</td><td>bool</td><td>false</td><td>Use Quarter Pel (do not use if using Quicktime Clients</td>
<tr align=center><td>xvid10UseLumimask</td><td>bool</td><td>false</td><td>Use XVID lumimask filter plugin</td>
<tr align=center><td>xvid10UseInterlace</td><td>bool</td><td>false</td><td>Use XVID interlace plugin</td>
</tbody>
</table>
<h3>Text Profile</h3>
<p>Text profile configuration variables are stored in an individual file per
stream in the .mp4live_d/Text directory.
<P>
<table border cellpadding=4 summary="Text Profiles">
<tbody>
<tr><th colspan=5 align=center><b>Text Profile Settings</b></tr></tbody>
<tbody>
<tr><th>Name</th><th>Type</th><th>Default</th><th>Does</th></tr>
<tr align=center><td>name</td><td>string</td><td>none</td><td>Mandatory Name</td></tr>
<tr align=center><td>textEncoding</td><td>string</td><td>href</td><td>Text encoding to use</td></tr>
<tr align=center><td>textRepeatTime</td><td>float</td><td>1.0</td><td>time in seconds to repeat last transmission</td></tr>
<tr align=center><td>hrefMakeAutomatic</td><td>bool</td><td>true</td><td>Urls without ISMA href markings get made Automatic</td></tr>
</tbody>
</table>
<p>
<a href="#top">Back to top</a>
<p>
Dave Mackie<br>
Bill May<br>
<a href="http://www.cisco.com">Cisco Systems, Inc.</a>
<p>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401"
alt="Valid HTML 4.01!" height="31" width="88"></a>
</p>
</body>
</html>