NAME vid-tag

Rename video files and set Title / Caption / Keywords metadata.

SYNOPSIS

First run. Create config file: ./vid-tag.conf

vid-tag -n -e "pEventId" [File1 File2 ...]

Edit config files, and/or use these options to override config file.

vid-tag -e "pEventId" File1 [File2 ...]
    [-p "pInitials"] [-P "pName"] [-C "pCaption"] [-R "pCopyright"]
    [-E "pEventTitle"] [-c "pCity"] [-k "pKeyword"]
    [-f "pFilePattern"] [-t "pTitlePattern"]
    [-z "pTimeZone"]
    [-n] [-h] [-H pStyle] [-v] [-d]

DESCRIPTION

vid-tag renames one or more video files and writes Title, Caption, and Keywords metadata using the exiftool. The file's Create Date metadata is read and used to date-stamp the output file name, the output title, and the file-system mtime.

Files are copied to the ./output/ directory, so the original files are not changed in any way.

Files (in ./output/) will be renamed using the pFilePattern and the EXIF values will be added to the renamed files

Large files, greater than 10 min, will be split into multiple 10 min parts (because some hosting sites do not allow "large" files). The exif time stamps for the split files will update for each 10 min part.

An example file, ./vid-tag-example.txt, will be created to show the changes that are (or will be) made to the files with the current settings. This is best used with the -n option and if you include all the files, the time stamps will match what is in the files.

If the timestamps for the files are "off" by a consistent amount the time-zone (-z) config option can be used to adjust the times.

The config options are read in this order (each layer overrides the previous):

Built-in script defaults.
Local config: ./vid-tag.conf If the file does not exist it will be created, and updated with the latest default settings.
Command-line options will override all other settings.

After all the values are set, the results are saved to ./vid-tag.conf so the next run will only need the -e option and the file list.

QUICK START

Install

Download the latest packaged zip file, vid-tag-VER.zip from

  https://moria.whyayh.com/rel/released/software/own/vid-tag/

Unpack the zip file to your "bin" dir.

Typical choices:
```
  /usr/local/bin
  $HOME/bin
  /opt/vid-tag
```
Just make sure the install dir is in your PATH env. var.

First run of vid-tag

cd to the directory with your video files (or the directory where you want ./output/ created). Copy the vid-tag.conf file from the install dir. This is optional. If missing a default version will be created.
```
  Run: vid-tag -n -e testevent
```
That will create or update ./vid-tag.conf and vid-tag-example.txt files.
You can now edit the vid-tag.conf file, or use the command line options to update the file. You want to change "testevent" to a short ID that will be put in your renamed video files. See the -e option.

Tips

See the -f option for how you can change the file naming pattern, and the -t option for how you can change the Title pattern.
Use the -v option to see some progress information. Use -vv if you want to see more progress details.
After each run, the vid-tag.conf file is updated with any changes, and the vid-tag-example.txt file will summarize how the files are modified.
Between each run you should probably remove everything in the ./outputs/ directory. Or you can leave the files there and they will be skipped from any changes.
Use the -z option if the file time are off by a consistent ammount, because you forgot to set the current time with your camera, or your camera uses UTC times and you want them adjusted to the local time.

OPTIONS

-e "pEventId"

Short event tag used in file names. It is also the Id used to access the specific event details in the ./vid-tag.conf file. If the pEventId is not found, then it will be added to vid-tag.conf.

The value will be changed to lower-case and any spaces will be changed to '_'

Pattern token: %e. Config key: event.tag. Required: "pEventId"
-E "pEventTitle"

Long event name used in the title.

Pattern token: %E. Config key: event.title. Default: "Long event description."
-c "pCity"

City name.

Pattern token: %c. Config key: event.city. Default: "city name"
-C "pCaption"

Caption / description metadata.

Config key: com.caption. Default: "Copyright TERMS"
-p "pInitials"

Photographer's initials / short name (no spaces).

Pattern token: %p. Config key: com.name-short.
-P "pName"

Photographer's full name.

Pattern token: %P. Config key: com.name-long. Default: First Last
-R "pCopyright"

Copyright stamp.

Config key: com.copyright Default: "Copyright NAME YYYY"
-f "pFilePattern"

Output file-name pattern. Usually you will only use the lowercase pattern options, because they should not have any spaces or special characters in them.

Config key: com.file-pat. Default: %d_%e_%p_%f.
-t "pTitlePattern"

Title pattern. Usually you will use the uppercase pattern options, but the lowercase options can be used.

Config key: com.title-pat. Default: %D, %c, %E, by %P.
-k "pKeyword"

Comma-separated keyword list.

Config key: event.keyword. Default: "PBP, event"
-z "pTimeZone"

Config key: event.time-zone. Default: local (no conversion).

When set to a value other than local (or empty), each file's CreateDate is converted from pTimeZone to the host's local time before it is used for the output filename, and all the other EXIF time settings.

Pattern: UTC[+-]H or UTC[+-]H:MM. The UTC prefix is case-insensitive (utc-1 is accepted).

Examples:
```
  -z utc-1     # zone 1 hour ahead of UTC
  -z UTC+8     # zone 8 hours behind UTC
  -z UTC-5:30  # zone 5h30m ahead of UTC
  -z utc-8:03  # your PST time was off be 3 min.
  -z local     # explicit "no conversion"
```
-n

No-execute / dry-run. Validate inputs and create config file ./vid-tag.conf, but do not create output/, rename files, or modify metadata.
-h

Output this "long" usage help. This is the same as -H long.

-H pStyle

Output usage in a specific style:

  short|usage - short usage, text
  long|text   - full usage, text
  man         - man page
  html        - HTML page
  md          - Markdown
  
  int         - Output internal documentation as text.
  int-html    - Output internal documentation as html.
  int-md      - Output internal documentation as markdown.

-v

Verbose output. Repeat for more detail (-vv).

  (default) - warnings and errors only
  -v        - notice, warnings, and errors
  -vv       - info, notice, warnings, and errors

-V

Output the script's version.
-d

Debug level. Default: 0

Each -d increments the debug level. Debug messages will be printed if the debug level is greater than the debug message's debug level.

Pattern Tokens

%c   city name            (-c)
%d   file date short      "YYYY-MM-DD"
%D   file date long       "YYYY-MM-DD WWW"
%T   file date full       "YYYY-MM-DD_HH:MM:SS"
%e   event short          (-e)
%E   event long           (-E)
%f   original file name   (path stripped)
%p   photographer short   (-p)
%P   photographer long    (-P)

Config File Format

This is the config file (./vid-tag.conf) format. The value of $gpEventId is the primary key.

[vid-tag "com"]
    file-pat   = %d_%e_%p_%f (pFilePatern)
    title-pat  = %D, %c, %E, by %P. (pTitlePattern)
    name-long  = Photographer Name (pName)
    name-short = Initials (pInitial)
    copyright  = pCopyright
    caption    = pCaption
[vid-tag "pEventId"]
    title      = Long Event Title (pEventTitle)
    city       = pCity
    keyword    = word, word (pKeyword)
    time-zone  = UTC[+-]H[:MM] | local (pTimeZone) - optional
[vid-tag "extra"]
    FILE1      = extra title text for FILE1 - optional
    FILE2      = extra title text for FILE2 - optional
    ...

The [vid-tag "extra"] section is optional. Each key is the exact basename of an input file (case-sensitive); the value is the text that will be appended to that file's EXIF Title. Files without a matching key are unaffected.

The append rule: a single space follows the title's trailing '.', then the "extra" text, then a closing '.'.

time-zone - is optional. Omit (or set to local) to disable the CreateDate timezone conversion. See the -z option for the format and semantics.

RETURN VALUE

0 on success; non-zero on error.

ERRORS

+ No input files given.
+ exiftool is not installed or not on PATH.
+ File not found: <filename>

Warnings (processing continues):

+ No CreateDate in <file>; using file mtime
+ output/<file> already exists
+ target exists, skipping: <old> -> <new>
+ exiftool returned error on <file>

ENVIRONMENT

HOME, USER, Tmp, gpVerbose, gpDebug, gpConfLocal

FILES

vid-tag-N.N.zip

vid-tag      - this script
vid-tag.inc  - vid-tag functions
vid-tag.conf - sample config file describing tags for an event
bash-com.inc - utility functions
LICENSE      - GPLv2

./vid-tag-example.txt - lists the changes to files
./output/      - generated directory, with renamed copies of files

Generated files

vid-tag.conf - if missing, it will be created with defaults and CLI args
vid-tag-example.txt - lists the changes to files based on vid-tag.conf
output/      - generated directory, with renamed copies of files

vid-tag-test-N.N.zip

This package is for testing the vid-tag script. See the NOTES section

vid-tag.test - optional unit and CLI integration tests
shunit2.1    - unit test framework for vid-tag.test

vid-tag-test-input.zip (4.5G)

Optional video files used by vid-tag.test. Only needed for the testCli*Slow tests.

MVI_0107.MP4
MVI_0110.MP4
MVI_0746.MP4

NOTES

All of this code is maintained at:

https://github.com/TurtleEngr/vid-tag

The releases are marked with vN.N tags.

CAVEATS

This script is mainly for Linux systems. However, if you have CygWin installed on your Windows PC, and you have install the Required packages (and set your PATH env.) this could work. For MacOS you'll probably want to install "brew" to get the Required programs.

If you do get this running on Windows or MacOS, let me know, with an "issue" report, what you had to do to get it running. For example include programs needed, configuration directions, and any changes you made to the scripts.

DIAGNOSTICS

This tool comes with a test script to verify vid-tag script is working OK. Download these files:

vid-tag-test-VER.zip
vid-tag-test-input.zip (4.5G)

from: https://moria.whyayh.com/rel/released/software/own/vid-tag/

Unzip vid-tag-test-VER.zip to the install dir.

Unzip vid-tag-test-input.zip to a "test" directory. In the test directory run vid-tag.test.

If you don't have space for the vid-tag-test-input.zip files, just use the "fast" test option for vid-tag.test. For example:

vid-tag.test -T fast

BUGS

Report bugs at: https://github.com/TurtleEngr/vid-tag/issues

AUTHOR

Turtle Engineer

HISTORY

GPLv2 (c) Copyright (See LICENSE file for terms.)

cVer=1.3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NAME vid-tag

SYNOPSIS

DESCRIPTION

QUICK START

Install

First run of vid-tag

Tips

OPTIONS

Pattern Tokens

Config File Format

RETURN VALUE

ERRORS

ENVIRONMENT

FILES

vid-tag-N.N.zip

Generated files

vid-tag-test-N.N.zip

vid-tag-test-input.zip (4.5G)

SEE ALSO

NOTES

CAVEATS

DIAGNOSTICS

BUGS

AUTHOR

HISTORY

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
bash-com.inc		bash-com.inc
bash-com.test		bash-com.test
shunit2.1		shunit2.1
tidyxhtml.conf		tidyxhtml.conf
vid-tag		vid-tag
vid-tag.conf		vid-tag.conf
vid-tag.inc		vid-tag.inc
vid-tag.test		vid-tag.test

Folders and files

Latest commit

History

Repository files navigation

NAME vid-tag

SYNOPSIS

DESCRIPTION

QUICK START

Install

First run of vid-tag

Tips

OPTIONS

Pattern Tokens

Config File Format

RETURN VALUE

ERRORS

ENVIRONMENT

FILES

vid-tag-N.N.zip

Generated files

vid-tag-test-N.N.zip

vid-tag-test-input.zip (4.5G)

SEE ALSO

NOTES

CAVEATS

DIAGNOSTICS

BUGS

AUTHOR

HISTORY

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages