Browse Source

Add an initial man page (README.md)

tags/v0.2.0.0
Peter J. Jones 4 years ago
parent
commit
39b5b6e61f
2 changed files with 234 additions and 36 deletions
  1. 7
    0
      INSTALL.md
  2. 227
    36
      README.md

+ 7
- 0
INSTALL.md View File

@@ -0,0 +1,7 @@
# Installing Vimeta

Coming Soon.

## Creating the `man` Page

pandoc -s -t man README.md -o vimeta.1

+ 227
- 36
README.md View File

@@ -1,66 +1,257 @@
# Vimeta -- A video metadata batch editor
% VIMETA(1) Vimeta User Manual
% Peter J. Jones
% May 19, 2015

# NAME

vimeta - frontend for video metadata tagging tools

# SYNOPSIS

vimeta config [*options*]

vimeta movie [*options*] *FILE*

vimeta tv [*options*] [*FILE*]...

# DESCRIPTION

Vimeta is a tool to fetch video metadata from the interwebs and update
video files. For movies, metadata is pulled from [TheMovieDB][] while
[TheTVDB][] is used for TV episodes.
video files using a tagging tool.

[TheMovieDB][] is used as the source for movie and TV series metadata.
This means that an API key for TheMovieDB is required in order to use
Vimeta. Sign up for an account at TheMovieDB.com and create an API
key. See the *config* command for details on how to create a
configuration file that includes your API key.

[AtomicParsley][] is the default tagging tool used to update the
metadata in a video file. Any video tagging utility can be used as
long as it can be called from the command line. See the CONFIGURATION
section for details on specifying a tagging tool to Vimeta. If you
decide to use AtomicParsley it's highly recommended that you use the
fork maintained by `wez` at <https://bitbucket.org/wez/atomicparsley>.

# OPTIONS

The following command-line options are available to all of the
commands listed in the COMMANDS section.

`--verbose`
: Enable verbose output

`-d`, `--dry-run`
: Don't actually do anything. Instead, print out what would be
done. Automatically enables `--verbose`.

# COMMANDS

## vimeta \--version

Display the Vimeta version number and then exit.

## vimeta config [*options*]

Create a configuration file for Vimeta.

`-k`, `--key`=*STRING*
: The API key for TheMovieDB to record into the configuration file.

## vimeta movie [*options*] *FILE*

Look up movie metadata from TheMovieDB and tag a video file. Vimeta
will interactively prompt for a movie name and provide a list of
matching movies to choose from.

`-i`, `--id`=*ID*
: Avoid interactive prompting by supplying a movie ID
assigned by TheMovieDB.com.

## vimeta tv [*options*] [*FILE*]...

Look up TV series metadata from TheMovieDB and tag one or more video
files. Episode video files can be given on the command line or
specified using a mapping file. See MAPPING FILES for more
information about creating a file that maps episodes to video files.

Vimeta will interactively prompt for a search string and then list
matching TV series. The starting season number and starting episode
number should be given on the command line or they will default to 1.
Each video file will be assigned the next episode number in the
series. Vimeta is smart enough to switch to the next season after the
last episode of the specified season.

`-s`, `--season`=*NUMBER*
: Specify the starting season number to tag into the episode files.
The season number will be incremented after the last episode of a
season is tagged. If the season number isn't specified it will
default to 1.

`-e`, `--episode`=*NUMBER*
: Specify the staring episode number. If not specified it defaults
to 1.

`-m`, `--map`=*FILE*
: Use *FILE* as a mapping file. The mapping file should contain
two columns, the first specifies the season and episode numbers
and the second the file name for the episode video file. See the
MAPPING FILE section for more details about mapping files.

`-i`, `--id`=*ID*
: Avoid interactive prompting by supplying a TV series ID
assigned by TheMovieDB.com.

# CONFIGURATION

The Vimeta configuration file is a YAML file containing a few keys.
You should begin by creating a default configuration file using the
*config* command.

## Description of Keys

`tmdb_key`
: The API key issued by TheMovieDB.

`cmd_movie`
: A format string used to execute a tagging tool for movie files.
See FORMAT STRINGS for more information.

`cmd_tv`
: A format string used to execute a tagging tool for TV episode
files. See FORMAT STRINGS for more information.

# FORMAT STRINGS

## Description

Vimeta uses format strings to specify the command to run in order to
tag video files, and the arguments needed to pass metadata to the
tagging utility. These format strings are similar to those used with
the `printf` family of functions and utilities.

In format stings, the percent character (`%`), followed by a single
character, is replaced by one of the metadata attributes. Percent
characters are removed and do not appear in the output string.
Therefore, if you need a literal percent character to appear in the
output string, you should use two percent characters (`%%`).

Format strings in Vimeta can also contain conditional parts. These
are introduced with the `%{` format specifier, which must be
terminated with the `%}` format specifier. The text and any format
specifiers enclosed inside the opening and closing brackets are only
injected into the output string if all of the enclosed format
specifiers have valid values.

As an example, not all movies have release dates. Supplying a
command-line flag along with a blank release date to a tagging tool
will most likely cause a problem. It would be best to avoid using the
command-line flag altogether. The following example does just this:

somecommand %{ --release-date %Y %}

Here, `%Y` stands in for the full release date. If it's not present
in the metadata then none of the text between the brackets will be
injected into the output string. If multiple format specifiers are
used, all of them have to be present in the metadata for any of the
text between the brackets to be included in the output text.

## Format Specifiers for Movies

The following format specifiers are available for tagging movie files.
Not all specifiers are guaranteed to be present. Consider using
conditional specifiers.

`%Y`
: Full release date in XML schema notation.

`%a`
: Path to a temporary file containing a movie poster image file.

`%d`
: Movie description (summary text, truncated to 255 characters).

[AtomicParsley][] is currently used to update the metadata in a file.
`%f`
: Path to the video file to be tagged.

This tool isn't very user friendly. There are no current plans to
change this but patches are welcome.
`%g`
: Name of first listed genre.

# Installation
`%t`
: Movie title.

Dependencies:
`%y`
: Release year.

* The [Haskell Platform][].
## Format Specifiers for Episodes

* [AtomicParsley] installed and in your `PATH`.
The following format specifiers are available for tagging TV episode
files. Not all specifiers are guaranteed to be present. Consider
using conditional specifiers.

* Haskell [library][hsm] for TheMovieDB.
`%Y`
: Full air date in XML schema notation.

* Haskell [library][hst] for TheTVDB.
`%a`
: Path to a temporary file containing a season poster image file.

Installation:
`%d`
: Episode description (summary text, truncated to 255 characters).

cabal configure && cabal build && cabal install
`%e`
: Episode number.

# Usage
`%f`
: Path to the video file to be tagged.

## Get API Keys
`%n`
: Name of the TV series.

Before you can use `vimeta` you need to create accounts and request
API keys from [TheMovieDB] and [TheTVDB].
`%s`
: Season number.

* Place your [TheMovieDB] API key in: `~/.tmdbkey`
`%t`
: Episode name.

* Place your [TheTVDB] API key in: `~/.tvdbkey`
`%y`
: Year that the episode aired.

## Movies
# MAPPING FILES

1. Fetch the movie ID from [TheMovieDB][]:
Vimeta can use mapping files that specify hints about metadata and
which video files to tag. For example, the *tv* command can use
mapping files to link video files to specific season and episode
numbers.

tmdb search "back to the future"
Mapping files are plain text files that contain two columns separated
by whitespace. Comments and blank lines are ignored. Comments begin
with a pound sign (`#`) and continue to the end of the line.

2. Update the video metadata:
The first column should contain information relevant to the command
using the mapping file. For example, the *tv* command expects the
first column to specify the season and episode number.

vimeta movie -i 105 file.m4v
The second column is always a file name. If the file doesn't exist
and the file name lacks a file extension, `.m4v` will be added to the
file name automatically.

## TV Episodes
Example mapping file for the *tv* command:

Assuming that you have two files for season 3 episodes 4 and 5:
# This is a comment.
S2E3 track03.m4v # Season 2, Episode 3
S3E1 track01.m4v # Season 3, Episode 1

1. Fetch the series ID from [TheTVDB][]:
# EXAMPLES

tvdb search "how I met your mother"
## Tag Several Episode Files

2. Update the metadata in the files:
vimeta tv -s 3 -e 10 file01.m4v file02.m4v

vimeta tv -i 75760 -s 3 -e 4 episode4.m4v episode5.m4v
With this command, Vimeta will prompt for the name of the TV series
and then search TheMovieDB. It will then generate a menu where the
correct TV series can be chosen. Both files will be tagged as
belonging to season 3. The first file is episode 10 and the second
file is episode 11. (For more control over how season and episode
numbers are assigned to files, see the section on MAPPING FILES.)

[TheMovieDB]: http://www.themoviedb.org/
[TheTVDB]: http://thetvdb.com/
[AtomicParsley]: http://atomicparsley.sourceforge.net/
[Haskell Platform]: http://www.haskell.org/platform/
[hsm]: https://github.com/pjones/themoviedb
[hst]: https://github.com/pjones/thetvdb
[AtomicParsley]: https://bitbucket.org/wez/atomicparsley

Loading…
Cancel
Save