File naming
Overview
The camera will create a default filename if none is specified. The user can also specify a filename. The specified filename can contain parameters that will be expanded by the camera to the actual value for that particular video capture when the file is created.
The camera determines which available storage device to use based on the following priority:
- USB removable storage device
- SD card removable storage device
- Network storage device
Because of this priority, if you want to save to a network storage device, you should specify a fully qualified filename (FQFN), as described below.
The selected storage device based on the above priority is called the active storage device. The camera continues to use the selected active storage device until it is no longer usable, independent of storage devices being inserted or removed.
The user can override the above priority by either making storage devices unavailable, meaning using CAMAPI to unmount them, or by specifying an a filename that includes an absolute path.
In addition to specifying the filename, you can also include a path. The camera will create directories as necessary to be able to save the file using the supplied path. A path that starts with a forward slash / character is called a fully qualified filename (FQFN). You can also include directories in the filename, which will save the file to the active storage device.
Specifying the storage device to use
Instead of using the camera's active storage device, you can specify which storage device to use by including a fully qualified filename (FQFN), which means the filename starts with a forward slash / character. To specify the storage device to use, start the filename with one of the strings as shown in the table below:
| Storage Device | Start of the FQFN | Example |
|---|---|---|
| SD card | /mnt/sdcard | /mnt/sdcard/DCIM/example_%c |
| USB storage | /mnt/usb | /mnt/usb/DCIM/example_%c |
| Network storage | /mnt/net | /mnt/net/game_1/inning_5/example_%c |
Characters allowed in a filename
Valid characters for a video filename include
- Upper and lower case letters
- Digits (numbers)
- Special characters period '.', underscore '_', minus '-', plus '+'
- Directory separator forward slash '/'
- Parameter indicator ampersand '&'
All other characters are convered to an underscore '_'.
Directory naming
If the filename does not contain a forward slash, meaning no directory path is specified in the filename, the video files and metadata files will be stored in the directory named DCIM on the active storage device. The camera creates the directory if it doesn't exist.
User specified file naming
CAMAPI allows you to specify the filename pattern via the methods run(), reconfigure_run(), trigger(), and selective_save(). The CAMAPI methods run() and reconfigure_run() accept a dictionary with the key requested_filename_pattern.
File naming parameters
The following ampersand parameters can be included in the filename pattern. When the video file or associated metadata file is saved, the camera will substitute the actual value in place of each ampersand parameter.
| Variable | Camera Setting |
|---|---|
| &D | Default version 2.2 naming scheme (described above) |
| &a | Camera name - string assigned via run() or reconfigure_run() or configure_save() |
| &m | Camera model - SC1 SC2X, etc. |
| &n | Serial number |
| &b | Multishot buffer |
| &d | Trigger date (DD-MMM-YY) |
| &e | Ending frame number where frame 0 is the trigger frame |
| &s | Starting frame number where frame 0 is the trigger frame |
| &t | Trigger time (HH-MM-SS) |
| &T | Integer Epoch trigger time (seconds since Jan 1, 1970) |
| &v | Floating point Epoch trigger time (seconds since Jan 1, 1970 GMT) |
| &c | Number of videos saved since camera was built. This value is also returned by CAMAPI get_camstatus(). |
| &C | Number of video saved since CAMAPI run() was last invoked. |
To keep from overwriting an existing files, once the above substitutions are done, if the created filename will overwrite an existing file, then an underscore and a number is appended to make the filename unique.
CAMAPI file naming support
There are several ways CAMAPI supports user specified filenames, list in highest to lowest priority order:
- selective_save() parameter
- trigger() parameter
- reconfigure_run() with requested_filename_pattern key in dictionary parameter
- run() with requested_filename_pattern key in dictionary parameter
- camera default filename_patttern value ("&D")
The filename is determined at the time the camera starts saving the movie file and metadata file. If the user trims the video while saving, the filename might change if the ending video frame number is included in the filename.
Default file naming scheme
If no filename pattern is specified, the camera will use "&D", which behaves as follows:
slomo_&T.mov
where &T is replaced with the seconds from the start of the computer epoc (Jan 1, 1970) GMT.
For multishot videos, the file naming convention was:
slomo_&T_&b.mov
where &b is replaced with the multishot buffer number.
For selective save, the start and end frame are included in the filename:
slomo_&T_frames_&s_to_&e.mov
A similar pattern is used for the metadata file:
slomo_&T.txt slomo_&T_&b.txt slomo_&T_frames_&s_to_&e.txt