Rename last video

Renames the most recently triggered, queued, or saved video.

Available since v2.5.1 software release.

Race condition warning

There are some automated workflows, such as capturing every pitch in a baseball game, where the desired video file name is not known when the camera is triggered. In such workflows, the video coaching software generates the name based on the pitch outcome. The CAMAPI rename_last_video() method was added to meet this need.

By its very definition, it is the last video that is renamed. By simply changing the timing, you may find the wrong video gets renamed. If you are capturing and saving many videos, such as in a baseball game, there is a race condition where what the software controlling the camera thinks is the last video and what is actually the last (or, more precisely, the most recently triggered, queued, or saved) video in the camera.

It is recommended you provide the filename, or filename pattern, with the CAMAPI run() or trigger() method, as there are not race condition with this use model. You can also provide the filename if you are using multi-cast trigger.

For rename_last_video() to be useful, you must have either long post trigger durations or long save durations compared to the time the software that is controlling the camera take to issue the rename command.

CAMAPI rename_last_video() method

rename_last_video(filename, stage)

Renames the most recently triggered (stage=RENAME_STAGE_TRIGGERED), queued (stage=RENAME_STAGE_QUEUED), or saved (stage=RENAME_STAGE_SAVED) video. Also renames the matching metadata file. If back-to-back triggering or saving is occurring, then depending on the timing, you may rename a different video than intended. The rename_last_video() method behavior depends on the camera state, which changes with time.

If the stage parameter is triggered, then the video currently filling the post trigger buffer or if the capture is complete, the more recently captured video is renamed.

If the stage parameter is queued, then the video that was most recently captured is renamed. The most recently captured video may be in the process of being saved.

If the stage parameter is saved, or is not specified, then the last saved video will be renamed.

The new filename can be in the form:

• base filename - e.g. new_name
• filename with extension - e.g. new_name.mov
• fully qualified filename - e.g. /mnt/sdcard/DCIM/new_name.mov

where new_name stands for any legal filename string.

The stage parameter can have one of these enumerated values:

RENAME_STAGE_SAVED 0
RENAME_STAGE_TRIGGERED 1
RENAME_STAGE_QUEUED 2

The rename_last_video() method returns the CAMAPI_STATUS_* outcome.

Examples

Rename the triggered video. This means the video whose frames are going into the post trigger buffer, or if the camera is not in the triggered state, then then the video that was most recently being captured. This video may be in the process of being saved.

camapi.rename_last_video("sammys-4-pitch-to-hank-in-the-4-inning", RENAME_STAGE_TRIGGERED)
http://10.11.12.13/rename_last_video?filename=sammys-4-pitch-to-hank-in-the-4-inning&stage=1

Video rename interaction with camera state

Stage	Save mode	Camera capture state	Save state	Count of queued videos ready to be saved	Action
TRIGGERED	Any	UNCONFIGURED CALIBRATING TRIGGER_CANCELED REVIEWING	Any	Any	Ignored. Renaming video in any of these camera states makes no sense.
QUEUED	Any	UNCONFIGURED CALIBRATING REVIEWING	Any	Any	Ignored. Renaming video in any of these camera states makes no sense.
TRIGGERED	AUTO BACKGROUND*	RUNNING RUNNING_PRETRIGGER_FULL	not IDLE	Any	Rename last captured video.
TRIGGERED	AUTO BACKGROUND*	TRIGGERED	N/A	Any	Rename video being captured. This is the intended trigger stage use case.

CAMAPI_STATE_SAVING  = 5

CAMAPI_STATE_SAVE_INTERRUPTED = 9
CAMAPI_STATE_SAVE_TRUNCATING = 10
CAMAPI_STATE_REVIEWING = 11
CAMAPI_STATE_SELECTIVE_SAVING = 12


RENAME_STAGE_SAVED 0
RENAME_STAGE_TRIGGERED 1
RENAME_STAGE_QUEUED 2

CAMAPI_STATE_UNCONFIGURED = 1
CAMAPI_STATE_CALIBRATING = 2
CAMAPI_STATE_RUNNING = 3
CAMAPI_STATE_TRIGGERED = 4
CAMAPI_STATE_SAVING  = 5
CAMAPI_STATE_RUNNING_PRETRIGGER_FULL = 6
CAMAPI_STATE_TRIGGER_CANCELED = 7
CAMAPI_STATE_SAVE_INTERRUPTED = 9
CAMAPI_STATE_SAVE_TRUNCATING = 10
CAMAPI_STATE_REVIEWING = 11
CAMAPI_STATE_SELECTIVE_SAVING = 12
CAMAPI_STATE_BUFFERS_FULL_TRIGGER_DISABLED = 13 # used internal to camera
CAMAPI_STATE_WAITING_FOR_SAVE_TO_COMPLETE_TRIGGER_DISABLED = 14 # used internal to camera

CAMAPI_SAVE_STATE_IDLE = CAMAPI_STATE_UNCONFIGURED
CAMAPI_SAVE_STATE_SAVING = CAMAPI_STATE_SAVING
CAMAPI_SAVE_STATE_SAVE_INTERRUPTED = CAMAPI_STATE_SAVE_INTERRUPTED
CAMAPI_SAVE_STATE_SAVE_TRUNCATING = CAMAPI_STATE_SAVE_TRUNCATING
CAMAPI_SAVE_STATE_SELECTIVE_SAVING = CAMAPI_STATE_SELECTIVE_SAVING

SAVE_MODE_AUTO = 0
SAVE_MODE_REVIEW = 1
SAVE_MODE_BACKGROUND = 2       # FIFO
SAVE_MODE_BACKGROUND_LIFO = 3