Flvtool2 – Flash Video (flv) Metadata / Cue Point Injector and Cutting Tool

I’m a couple of years late to this party, but there’s a neat Ruby based tool, Flvtool2, which allows you to stamp metadata in flv files, insert cue points–both navigation and event, and allows you to slice and dice an flv file based on defined in and out points (kudos to Norman Timmler for writing this app and making it available to the community).

Unfortunately, the documentation for this tool is almost non-existent – SPAM apparently took down the wiki. Another problem, I encountered at least, is that the builds available from RubyForge contain bugs. Fortunately, you can download the source from svn where the bugs appear to be fixed.

Since the documentation is so sparse I thought I’d post some example usage where the search bots might possibly find it.

If you wish to insert onCuePoint events into your flv, Flvtool2 accepts an xml / yaml file that declares the cue point data. The screen shot below illustrates how you can insert both “event” and “navigation” cue points. Navigation cue points should theoretically corresponds to a keyframe stamp so that an flv seek action can be assured of starting from the given timestamp.
xml tag declarations used by flvtool2

You can view a list of of the possible commands by typing the following in your commandline shell.

flvtool2 -h

To simply print out all of the metadata for a given flv simply use the following command.

flvtool2 -P some.flv

To insert cue points declared in the tags.xml file use the -A command with the -t switch. In the example below I’ll actually chain a few commands together (Add, Print, Update). The -P prints the metadata from the given file to stdout and the -U updates the flv with an onMetaTag event.

flvtool2 -APUt tags.xml src.flv output.flv

Here’s what running the proceeding code might look like.

The next example illustrates how to carve a new flv that’s four seconds long from the source flv based on in / out timestamps in milliseconds. To do this use the -C command along with the -i / -o switches.

flvtool2 -Cio 1000 5000 src.flv splice.flv

If you are interested in using flvtool2 as part of an automated ant build script you’ll need to invoke Ruby via the exec task, pass in flvtool as the ruby application to run and then pass in the desired commands, switches and arguments. The screenshot below is an example of this in action.

So there are just a ton of applications for a tool like this for both client and server-side applications which should be obvious to just about everyone likely to read this post. If you’re bored, it’s also extremely interesting to to take a peek at the metadata injected by various commercial encoders or video sharing sites (gootube et al). Enjoy!

32 thoughts on “Flvtool2 – Flash Video (flv) Metadata / Cue Point Injector and Cutting Tool

  1. Hi,Brooks
    As flvtool2 can’t modify the timestamp when using the -C option. Is there any tool that could set the starting timestamp to zero or any that could merge two or more flv files to one ?
    Thanks,
    peterman

  2. Hi Folks,

    I have a question reguarding the size limit of xtradata meta which can be included into FLV file. Any idea experience about that ?

    I planned to include meta information about content directly into the FLV as speech transcription or subtitles or whatever. Is this way good ?

    Thanks for any answer.

  3. I used mencoder to create flash files, but the header is not ‘FLV’ as expected, my files have this header:’FWS’. I don’t know enough about mencoder or flash to understand the difference – is this critical?

    I manually changed the header and ran flvtool again, but ran into another issue:
    ERROR: bignum too big to convert into `long’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flv/core_extensions.rb:86:in `read’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flv/core_extensions.rb:86:in `read__STRING’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flv/stream.rb:408:in `read_header’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flv/stream.rb:57:in `initialize’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2/base.rb:272:in `new’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2/base.rb:272:in `open_stream’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2/base.rb:238:in `process_files’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2/base.rb:225:in `each’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2/base.rb:225:in `process_files’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2/base.rb:44:in `execute!’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2.rb:168:in `execute!’
    ERROR: /usr/lib/ruby/site_ruby/1.8/flvtool2.rb:228
    ERROR: /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `gem_original_require’
    ERROR: /usr/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:27:in `require’
    ERROR: /usr/bin/flvtool2:2

    Help please?

  4. the -C option is not updating the metadata. can anyone tell me how can i update the metadata too. i alredy used the metadata injectors but nothing works they still show the old timestamp after cutting…. any idea…

    Thanks

  5. Hi,

    how can i use the -i and -o commands? For example i have a 2 minutres video,but i just want to have the first minute. What is the correct command?

    thx in advance

  6. Hi, I tried injecting cuepoints into a FLV, followed every steps of this tutorial, but when my video plays, I get the error:

    Error #2044: Unhandled AsyncErrorEvent:. text=Error #2095: flash.net.NetStream was unable to invoke callback onCuePoint. error=TypeError: Error #2007: Parameter definitionName must be non-null.

    The problem is with the FLV, because I tested with other FLVs and the cuepoints do trigger without any error… I only get this error when I play this one.

    I tried opening it in RichFLV, and the cuepoint names are indeed empty. They should be named “onCuePoint”. When I open other FLVs, they are all named onCuePoint…

  7. Hi, I have a 2.6G flv file and I like to extract the first two minutes chunk. My linux box hung when I issued the following command:
    flvtool2 -Co 120000 infile.flv outfile.flv

    Is the file size too big for flvtool2? or is it the command incomplete? Thanks.

  8. Hi,Brooks
    I’ve got some recorded flv clips with wrong timestamp (e.g. starting 358:28:41, ending 10000:00:00). Is it possible to set the starting timestamp to zero (BTW, I don’t know the total duration of the clips)? I’d appreciate it if you could just send me a step-by-step illustration of how to achieve that goal.
    Thank you very much!
    Leo

  9. Hi, Brooks. I posted a question earlier about a recorded flv file. I’ve tried the chain command “-UPs” only to get the following results. What can be done? Would you send me a detailed solution? Thanks a lot.
    E:\flvtool2-1.0.6>flvtool2 -UPs t84.flv

    E:/flvtool2-1.0.6/t84.flv:
    hasKeyframes: true
    cuePoints:
    audiodatarate: 3.47117025958881
    hasVideo: true
    stereo: true
    canSeekToEnd: false
    framerate: 25
    audiosamplerate: 44000
    videocodecid: 7
    datasize: 7426372
    lasttimestamp: 2203.87
    audiosamplesize: 16
    audiosize: 1010008
    hasAudio: true
    audiodelay: 2076.186
    videosize: 6414705
    metadatadate: Tue Sep 22 09:18:48 GMT+0800 2009
    metadatacreator: inlet media FLVTool2 v1.0.6 – http://www.inlet-media.de/flvto
    ol2
    lastkeyframetimestamp: 2202.27
    height: 384
    filesize: 7458721
    hasMetadata: true
    keyframes:
    times:
    – 2076.186
    – 2076.186
    – 2082.175
    – 2088.175
    – 2093.932
    – 2099.932
    – 2105.967
    – 2108.007
    – 2108.847
    – 2112.715
    – 2114.915
    – 2120.915
    – 2125.592
    – 2126.992
    – 2127.872
    – 2129.512
    – 2130.512
    – 2132.584
    – 2136.184
    – 2138.664
    – 2139.744
    – 2141.464
    – 2144.772
    – 2146.492
    – 2148.492
    – 2152.008
    – 2154.408
    – 2156.848
    – 2160.768
    – 2166.16
    – 2172.003
    – 2178.003
    – 2183.239
    – 2189.239
    – 2191.95
    – 2197.95
    – 2202.27
    filepositions:
    – 1646
    – 1705
    – 371461
    – 699395
    – 967953
    – 1280001
    – 1620885
    – 1807495
    – 1876533
    – 2094258
    – 2293453
    – 2585122
    – 2745607
    – 2875298
    – 2942415
    – 3059361
    – 3147496
    – 3264635
    – 3427629
    – 3616175
    – 3670500
    – 3760953
    – 3997038
    – 4117494
    – 4252851
    – 4470122
    – 4614280
    – 4762854
    – 4942785
    – 5321481
    – 5650529
    – 5935662
    – 6254936
    – 6663421
    – 6818706
    – 7135580
    – 7388000
    audiocodecid: 2
    videodatarate: 23.1577034943077
    duration: 2203.91
    hasCuePoints: false
    width: 512

  10. I’m trying to add cue points with FLVTools2 1.0.6 and xml-file:

    33 seconds
    33
    navigation

    After executing command:
    flvtool2 -AUPt abc.xml input_file.flv output_file.flv

    I got errors:
    ERROR: undefined method `to_i’ for {:cdata=>”33″}:Hash
    ERROR: flvtool2/base.rb:72:in `add’
    ERROR: flvtool2/base.rb:88:in `call’
    ERROR: flvtool2/base.rb:88:in `add’
    ERROR: flvtool2/base.rb:82:in `each’
    ERROR: flvtool2/base.rb:82:in `add’
    ERROR: flvtool2/base.rb:47:in `send’
    ERROR: flvtool2/base.rb:47:in `execute!’
    ERROR: flvtool2/base.rb:46:in `each’
    ERROR: flvtool2/base.rb:46:in `execute!’
    ERROR: flvtool2/base.rb:239:in `process_files’
    ERROR: flvtool2/base.rb:225:in `each’
    ERROR: flvtool2/base.rb:225:in `process_files’
    ERROR: flvtool2/base.rb:44:in `execute!’
    ERROR: flvtool2.rb:168:in `execute!’
    ERROR: flvtool2.rb:228

    Is something wrong in my xml-file?

  11. A xml-content was filtered so there is content of xml-file without brackets:

    tags
    metatag event=”onCuePoint”
    name 33 seconds /name
    timestamp 33 /timestamp
    type navigation /type
    /metatag
    /tags

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>