freebsd-ports/multimedia/flvmeta/files/patch-man_flvmeta.1

--- man/flvmeta.1.orig	2022-11-13 06:34:24 UTC
+++ man/flvmeta.1
@@ -0,0 +1,458 @@
+.\" Automatically generated by Pandoc 2.19.2
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.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[R] \f[I]INPUT_FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]flvmeta\f[R] \f[I]INPUT_FILE\f[R] \f[I]OUTPUT_FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]flvmeta\f[R] \f[V]-D\f[R]|\f[V]--dump\f[R] [\f[I]options\f[R]]
+\f[I]INPUT_FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]flvmeta\f[R] \f[V]-F\f[R]|\f[V]--full-dump\f[R] [\f[I]options\f[R]]
+\f[I]INPUT_FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]flvmeta\f[R] \f[V]-C\f[R]|\f[V]--check\f[R] [\f[I]options\f[R]]
+\f[I]INPUT_FILE\f[R]
+.PD 0
+.P
+.PD
+\f[B]flvmeta\f[R] \f[V]-U\f[R]|\f[V]--update\f[R] [\f[I]options\f[R]]
+\f[I]INPUT_FILE\f[R] [\f[I]OUTPUT_FILE\f[R]]
+.SH DESCRIPTION
+.PP
+\f[B]flvmeta\f[R] 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[R] 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[R] 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[R] event, used to
+signal the end of playback, for example to revert the player software to
+a `stopped' state.
+.PP
+\f[B]flvmeta\f[R] 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[R] 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\[cq]s tags headers in memory.
+.SH COMMANDS
+.PP
+Only one command can be specified for an invocation of
+\f[B]flvmeta\f[R].
+The chosen command determines the mode of execution of the program.
+.PP
+By default, if no command is specified, \f[B]flvmeta\f[R] will
+implicitly choose the command to use according to the presence of
+\f[I]INPUT_FILE\f[R] and \f[I]OUTPUT_FILE\f[R].
+.PP
+If only \f[I]INPUT_FILE\f[R] is present, the \f[B]--dump\f[R] command
+will be executed.
+.PP
+If both \f[I]INPUT_FILE\f[R] and \f[I]OUTPUT_FILE\f[R] are present, the
+\f[B]--update\f[R] 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[R] tag
+found in \f[I]INPUT_FILE\f[R] 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[R]
+option, such as \f[I]onLastSecond\f[R].
+.SS -F, --full-dump
+.PP
+Dump a textual representation of the whole contents of
+\f[I]INPUT_FILE\f[R] 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[R], 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[R] option, or JSON using the \f[B]--json\f[R] option.
+It can also be disabled altogether using the \f[B]--quiet\f[R] 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[R]: informational messages that do not pertain to the file
+validity
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]warning\f[R]: 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[R]: 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[R]: messages that inform of errors that make further file
+reading impossible therefore ending parsing completely
+.PP
+The \f[B]--level\f[R] option allows \f[B]flvmeta\f[R] 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[V][level][topic][id]\f[R]
+.IP \[bu] 2
+\f[B]level\f[R] 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[R] is a two-digit integer representing the general topic of
+the message
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]id\f[R] 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[R] general flv file format
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]11\f[R] file header
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]12\f[R] previous tag size
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]20\f[R] tag format
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]30\f[R] tag types
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]40\f[R] timestamps
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]50\f[R] audio data
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]51\f[R] audio codecs
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]60\f[R] video data
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]61\f[R] video codecs
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]70\f[R] metadata
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]80\f[R] AMF data
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]81\f[R] keyframes
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]82\f[R] 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[R]
+tag.
+If \f[I]OUTPUT_FILE\f[R] 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[R] tag will be inserted, unless the
+\f[B]--no-last-second\f[R] 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[R] option.
+.PP
+It is also possible to insert custom string values with the
+\f[B]--add\f[R] option, which can be specified multiple times.
+.PP
+By default, the update operation is performed without output, unless the
+\f[B]--verbose\f[R] option is specified, or the
+\f[B]--print-metadata\f[R] is used to print the newly written metadata
+to the standard output.
+.SH OPTIONS
+.SS DUMP
+.TP
+-d \f[I]FORMAT\f[R], --dump-format=\f[I]FORMAT\f[R]
+specify dump format where \f[I]FORMAT\f[R] is `xml' (default), `json',
+`raw', or `yaml'.
+Also applicable for the \f[B]--full-dump\f[R] command.
+.TP
+-j, --json
+equivalent to \f[B]--dump-format=json\f[R]
+.TP
+-r, --raw
+equivalent to \f[B]--dump-format=raw\f[R]
+.TP
+-x, --xml
+equivalent to \f[B]--dump-format=xml\f[R]
+.TP
+-y, --yaml
+equivalent to \f[B]--dump-format=yaml\f[R]
+.TP
+-e \f[I]EVENT\f[R], --event=\f[I]EVENT\f[R]
+specify the event to dump instead of \f[I]onMetaData\f[R], for example
+\f[I]onLastSecond\f[R]
+.SS CHECK
+.TP
+-l \f[I]LEVEL\f[R], --level=\f[I]LEVEL\f[R]
+print only messages where level is at least \f[I]LEVEL\f[R].
+The levels are, by ascending importance, `info', `warning' (default),
+`error', or `fatal'.
+.TP
+-q, --quiet
+do not print messages, only return the status code
+.TP
+-x, --xml
+generate an XML report instead of the default `compiler-friendly' text
+.TP
+-j, --json
+generate a JSON report instead of the default `compiler-friendly' text
+.SS UPDATE
+.TP
+-m, --print-metadata
+print metadata to stdout after update using the format specified by the
+\f[B]--format\f[R] option
+.TP
+-a \f[I]NAME=VALUE\f[R], --add=\f[I]NAME=VALUE\f[R]
+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[R] tag.
+.TP
+-s, --no-lastsecond
+do not create the \f[I]onLastSecond\f[R] tag
+.TP
+-p, --preserve
+preserve input file existing \f[I]onMetadata\f[R] tags
+.TP
+-f, --fix
+fix invalid tags from the input file
+.TP
+-i, --ignore
+ignore invalid tags from the input file (the default behaviour is to
+stop the update process with an error)
+.TP
+-t, --reset-timestamps
+reset timestamps so \f[I]OUTPUT_FILE\f[R] 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.
+.TP
+-k, \[en]all-keyframes
+index all keyframe tags, including duplicate timestamps
+.SS GENERAL
+.TP
+-v, --verbose
+display informative messages
+.TP
+-V, --version
+print version information and exit
+.TP
+-h, --help
+display help on the program usage and exit
+.SH FORMATS
+.PP
+The various XML formats used by \f[B]flvmeta\f[R] 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[R] \f[B]--xml\f[R] command
+.SH EXAMPLES
+.PP
+\f[B]flvmeta example.flv\f[R]
+.PP
+Prints the onMetadata tag contents of example.flv as XML output.
+.PP
+\f[B]flvmeta example.flv out.flv\f[R]
+.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[R]
+.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[R]
+.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[R]
+.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[R] flvmeta exited without error
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]1\f[R] an error occurred when trying to open an input file
+.IP \[bu] 2
+\f[B]2\f[R] the input file was not recognized as an FLV file
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]3\f[R] an end-of-file condition was encountered unexpectedly
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]4\f[R] a memory allocation error occurred during the run of the
+program
+.IP \[bu] 2
+\f[B]5\f[R] an empty tag was encountered in an input file
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]6\f[R] an error occurred when trying to open an output file
+.IP \[bu] 2
+\f[B]7\f[R] an invalid tag was encountered in an input file
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]8\f[R] an error was encountered while writing an output file
+.PD 0
+.P
+.PD
+.IP \[bu] 2
+\f[B]9\f[R] the \f[B]--check\f[R] command reported an invalid file (one
+or more errors)
+.SH BUGS
+.PP
+\f[B]flvmeta\f[R] does not support encrypted FLV files yet.
+.SH AUTHOR
+.PP
+Marc Noirot <marc.noirot\[at]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\[at]googlegroups.com>