.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "flvmeta" "1" "January 2014" "flvmeta user manual" ""
.hy
.SH NAME
.PP
flvmeta \- manipulate or extract metadata in Adobe Flash Video files
.SH SYNOPSIS
.PP
\f[B]flvmeta\f[] \f[I]INPUT_FILE\f[]
.PD 0
.P
.PD
\f[B]flvmeta\f[] \f[I]INPUT_FILE\f[] \f[I]OUTPUT_FILE\f[]
.PD 0
.P
.PD
\f[B]flvmeta\f[] \f[C]\-D\f[]|\f[C]\-\-dump\f[] [\f[I]options\f[]]
\f[I]INPUT_FILE\f[]
.PD 0
.P
.PD
\f[B]flvmeta\f[] \f[C]\-F\f[]|\f[C]\-\-full\-dump\f[] [\f[I]options\f[]]
\f[I]INPUT_FILE\f[]
.PD 0
.P
.PD
\f[B]flvmeta\f[] \f[C]\-C\f[]|\f[C]\-\-check\f[] [\f[I]options\f[]]
\f[I]INPUT_FILE\f[]
.PD 0
.P
.PD
\f[B]flvmeta\f[] \f[C]\-U\f[]|\f[C]\-\-update\f[] [\f[I]options\f[]]
\f[I]INPUT_FILE\f[] [\f[I]OUTPUT_FILE\f[]]
.SH DESCRIPTION
.PP
\f[B]flvmeta\f[] is a command\-line utility aimed at manipulating
Adobe(tm) Flash Video files (FLV), through several commands, only one of
which can be used for each invocation of the program.
.PP
It possesses the ability to compute and inject a variety of values in
the \f[I]onMetaData\f[] event tag, including keyframe indices used by
most video players to allow random\-access seeking, notably for HTTP
pseudo\-streamed files via a server\-side module, by having the client
send the file offset looked up for the nearest desired keyframe.
.PD 0
.P
.PD
Tools such as \f[B]flvmeta\f[] must be used in the case the initial
encoding process is unable to inject those metadata.
.PP
It can also optionnally inject the \f[I]onLastSecond\f[] event, used to
signal the end of playback, for example to revert the player software to
a `stopped' state.
.PP
\f[B]flvmeta\f[] also has the ability to dump metadata and full file
information to standard output, in a variety of textual output formats,
including XML, YAML, and JSON.
.PP
Finally, the program can analyze FLV files to detect potential problems
and errors, and generate a textual report as a raw format, as JSON, or
as XML.
It has the ability to detect more than a hundred problems, going from
harmless to potentially unplayable, using a few real world encountered
issues.
.PP
\f[B]flvmeta\f[] can operate on arbitrarily large files, and can handle
FLV files using extended (32\-bit) timestamps.
It can guess video frame dimensions for all known video codecs supported
by the official FLV specification.
.PP
Its memory usage remains minimal, as it uses a two\-pass reading
algorithm which permits the computation of all necessary tags without
loading anything more than the file's tags headers in memory.
.SH COMMANDS
.PP
Only one command can be specified for an invocation of \f[B]flvmeta\f[].
The chosen command determines the mode of execution of the program.
.PP
By default, if no command is specified, \f[B]flvmeta\f[] will implicitly
choose the command to use according to the presence of
\f[I]INPUT_FILE\f[] and \f[I]OUTPUT_FILE\f[].
.PP
If only \f[I]INPUT_FILE\f[] is present, the \f[B]\-\-dump\f[] command
will be executed.
.PP
If both \f[I]INPUT_FILE\f[] and \f[I]OUTPUT_FILE\f[] are present, the
\f[B]\-\-update\f[] command will be executed.
.PP
Here is a list of the supported commands:
.SS \-D, \-\-dump
.PP
Dump a textual representation of the first \f[I]onMetaData\f[] tag found
in \f[I]INPUT_FILE\f[] to standard output.
The default format is XML, unless specified otherwise.
.PD 0
.P
.PD
It is also possible to specify another event via the \f[B]\-\-event\f[]
option, such as \f[I]onLastSecond\f[].
.SS \-F, \-\-full\-dump
.PP
Dump a textual representation of the whole contents of
\f[I]INPUT_FILE\f[] to standard output.
The default format is XML, unless specified otherwise.
.SS \-C, \-\-check
.PP
Print a report to standard output listing warnings and errors detected
in \f[I]INPUT_FILE\f[], as well as potential incompatibilities, and
information about the codecs used in the file.
The exit code will be set to a non\-zero value if there is at least one
error in the file.
.PP
The output format can either be plain text, XML using the
\f[B]\-\-xml\f[] option, or JSON using the \f[B]\-\-json\f[] option.
It can also be disabled altogether using the \f[B]\-\-quiet\f[] option
if you are only interested in the exit status.
.PP
Messages are divided into four specific levels of increasing importance:
.IP \[bu] 2
\f[B]info\f[]: informational messages that do not pertain to the file
validity
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]warning\f[]: messages that inform of oddities to the flv format but
that might not hamper file reading or playability, this is the default
level
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]error\f[]: messages that inform of errors that might render the
file impossible to play or stream correctly
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]fatal\f[]: messages that inform of errors that make further file
reading impossible therefore ending parsing completely
.PP
The \f[B]\-\-level\f[] option allows \f[B]flvmeta\f[] to limit the
display of messages to a minimum level among those, for example if the
user is only interested in error messages and above.
.PP
Each message or message template presented to the user is identified by
a specific code of the following format:
.PP
\f[C][level][topic][id]\f[]
.IP \[bu] 2
\f[B]level\f[] is an upper\-case letter that can be either I, W, E, F
according to the aforementioned message levels
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]topic\f[] is a two\-digit integer representing the general topic of
the message
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]id\f[] is a unique three\-digit identifier for the message, or
message template if parameterized
.PP
Messages can be related to the following topics :
.IP \[bu] 2
\f[B]10\f[] general flv file format
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]11\f[] file header
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]12\f[] previous tag size
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]20\f[] tag format
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]30\f[] tag types
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]40\f[] timestamps
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]50\f[] audio data
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]51\f[] audio codecs
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]60\f[] video data
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]61\f[] video codecs
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]70\f[] metadata
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]80\f[] AMF data
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]81\f[] keyframes
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]82\f[] cue points
.PP
For example, represents a Warning in topic 51 with the id 050, which
represents a warning message related to audio codecs, in that case to
signal that an audio tag has an unknown codec.
.SS \-U, \-\-update
.PP
Update the given input file by inserting a computed \f[I]onMetaData\f[]
tag.
If \f[I]OUTPUT_FILE\f[] is specified, it will be created or overwritten
instead and the input file will not be modified.
If the original file is to be updated, a temporary file will be created
in the default temp directory of the platform, and it will be copied
over the original file at the end of the operation.
This is due to the fact that the output file is written while the
original file is being read due to the two\-pass method.
.PP
The computed metadata contains among other data full keyframe
information, in order to allow HTTP pseudo\-streaming and random\-access
seeking in the file.
.PP
By default, an \f[I]onLastSecond\f[] tag will be inserted, unless the
\f[B]\-\-no\-last\-second\f[] option is specified.
.PP
Normally overwritten by the update process, the existing metadata found
in the input file can be preserved by the \f[B]\-\-preserve\f[] option.
.PP
It is also possible to insert custom string values with the
\f[B]\-\-add\f[] option, which can be specified multiple times.
.PP
By default, the update operation is performed without output, unless the
\f[B]\-\-verbose\f[] option is specified, or the
\f[B]\-\-print\-metadata\f[] is used to print the newly written metadata
to the standard output.
.SH OPTIONS
.SS DUMP
.TP
.B \-d \f[I]FORMAT\f[], \-\-dump\-format=\f[I]FORMAT\f[]
specify dump format where \f[I]FORMAT\f[] is `xml' (default), `json',
`raw', or `yaml'.
Also applicable for the \f[B]\-\-full\-dump\f[] command.
.RS
.RE
.TP
.B \-j, \-\-json
equivalent to \f[B]\-\-dump\-format=json\f[]
.RS
.RE
.TP
.B \-r, \-\-raw
equivalent to \f[B]\-\-dump\-format=raw\f[]
.RS
.RE
.TP
.B \-x, \-\-xml
equivalent to \f[B]\-\-dump\-format=xml\f[]
.RS
.RE
.TP
.B \-y, \-\-yaml
equivalent to \f[B]\-\-dump\-format=yaml\f[]
.RS
.RE
.TP
.B \-e \f[I]EVENT\f[], \-\-event=\f[I]EVENT\f[]
specify the event to dump instead of \f[I]onMetaData\f[], for example
\f[I]onLastSecond\f[]
.RS
.RE
.SS CHECK
.TP
.B \-l \f[I]LEVEL\f[], \-\-level=\f[I]LEVEL\f[]
print only messages where level is at least \f[I]LEVEL\f[].
The levels are, by ascending importance, `info', `warning' (default),
`error', or `fatal'.
.RS
.RE
.TP
.B \-q, \-\-quiet
do not print messages, only return the status code
.RS
.RE
.TP
.B \-x, \-\-xml
generate an XML report instead of the default `compiler\-friendly' text
.RS
.RE
.TP
.B \-j, \-\-json
generate a JSON report instead of the default `compiler\-friendly' text
.RS
.RE
.SS UPDATE
.TP
.B \-m, \-\-print\-metadata
print metadata to stdout after update using the format specified by the
\f[B]\-\-format\f[] option
.RS
.RE
.TP
.B \-a \f[I]NAME=VALUE\f[], \-\-add=\f[I]NAME=VALUE\f[]
add a metadata string value to the output file.
The name/value pair will be appended at the end of the
\f[I]onMetaData\f[] tag.
.RS
.RE
.TP
.B \-s, \-\-no\-lastsecond
do not create the \f[I]onLastSecond\f[] tag
.RS
.RE
.TP
.B \-p, \-\-preserve
preserve input file existing \f[I]onMetadata\f[] tags
.RS
.RE
.TP
.B \-f, \-\-fix
fix invalid tags from the input file
.RS
.RE
.TP
.B \-i, \-\-ignore
ignore invalid tags from the input file (the default behaviour is to
stop the update process with an error)
.RS
.RE
.TP
.B \-t, \-\-reset\-timestamps
reset timestamps so \f[I]OUTPUT_FILE\f[] starts at zero.
This has been added because some FLV files are produced by cutting
bigger files, and the software doing the cutting does not resets the
timestamps as required by the standard, which can cause playback issues.
.RS
.RE
.TP
.B \-k, \[en]all\-keyframes
index all keyframe tags, including duplicate timestamps
.RS
.RE
.SS GENERAL
.TP
.B \-v, \-\-verbose
display informative messages
.RS
.RE
.TP
.B \-V, \-\-version
print version information and exit
.RS
.RE
.TP
.B \-h, \-\-help
display help on the program usage and exit
.RS
.RE
.SH FORMATS
.PP
The various XML formats used by \f[B]flvmeta\f[] are precisely described
by the following XSD schemas:
.IP \[bu] 2
http://schemas.flvmeta.org/flv.xsd: describes the general organization
of FLV files
.IP \[bu] 2
http://schemas.flvmeta.org/Amf0.xsd: describes an XML representation of
the Adobe(TM) AMF0 serialization format
.IP \[bu] 2
http://schemas.flvmeta.org/report.xsd: describes the XML output format
of the \f[B]\-\-check\f[] \f[B]\-\-xml\f[] command
.SH EXAMPLES
.PP
\f[B]flvmeta example.flv\f[]
.PP
Prints the onMetadata tag contents of example.flv as XML output.
.PP
\f[B]flvmeta example.flv out.flv\f[]
.PP
Creates a file named out.flv containing updated metadata and an
onLastSecond tag from the exemple.flv file.
.PP
\f[B]flvmeta \-\-check \-\-xml \-\-level=error example.flv\f[]
.PP
Checks the validity of the example.flv file and prints the error report
to stdout in XML format, displaying only errors and fatal errors.
.PP
\f[B]flvmeta \-\-full\-dump \-\-yaml example.flv\f[]
.PP
Prints the full contents of example.flv as YAML format to stdout.
.PP
\f[B]flvmeta \-\-update \-\-no\-last\-second \-\-show\-metadata \-\-json
example.flv\f[]
.PP
Performs an in\-place update of example.flv by inserting computed
onMetadata without an onLastSecond tag, and prints the newly inserted
metadata on stdout as JSON.
.SH EXIT STATUS
.IP \[bu] 2
\f[B]0\f[] flvmeta exited without error
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]1\f[] an error occurred when trying to open an input file
.IP \[bu] 2
\f[B]2\f[] the input file was not recognized as an FLV file
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]3\f[] an end\-of\-file condition was encountered unexpectedly
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]4\f[] a memory allocation error occurred during the run of the
program
.IP \[bu] 2
\f[B]5\f[] an empty tag was encountered in an input file
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]6\f[] an error occurred when trying to open an output file
.IP \[bu] 2
\f[B]7\f[] an invalid tag was encountered in an input file
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]8\f[] an error was encountered while writing an output file
.PD 0
.P
.PD
.IP \[bu] 2
\f[B]9\f[] the \f[B]\-\-check\f[] command reported an invalid file (one
or more errors)
.SH BUGS
.PP
\f[B]flvmeta\f[] does not support encrypted FLV files yet.
.SH AUTHOR
.PP
Marc Noirot <marc.noirot\@gmail.com>
.SH COPYRIGHT
.PP
Copyright 2007\-2016 Marc Noirot
.PP
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
.SH CONTACT
.PP
Please report bugs to <flvmeta\-discussion\@googlegroups.com>