VALT Python Module

VALT Class

The VALT Python class was written by Intelligent Video Solutions and is made available to our customers as an easy mechanism for accessing the VALT API.

https://github.com/IntelligentVideoSolutions/valt-python.git

Requests for additional features or support can be submitted at support@ipivs.com.

Class Specifications

Usage

Creates a class that is one instance of a connection to a VALT server. The below functions are all defined as part of the valt class and can be called.

Initiation

Upon initiation, the class will attempt to authenticate to the specified VALT server using the provided credentials. If authentication fails upon initiation or upon any further actions, the class will wait 30 seconds and then attempt to reauthenticate. Upon success, the class with reauthenticate every 24 hours.

Variables

Variable	Type	Value
username	string	Stores the username used to authenticate to VALT.
password	string	Stores the password used to authenticate to VALT.
baseurl	String	Stores the basic url to connect to valt. The url is composed of the valt server address. For example http://ivstest1.ad.ipivs.com/api/v3/
success_reauth_time	int	The number of seconds to wait before reauthenticating to VALT after a successful authentication. Default is 28800.
failure_reauth_time	int	The number of seconds to wait before reauthenticating to VALT after a failed authentication attempt. Default is 30.
accesstoken	string	Stores the current access token retrieved during the last successful authentication. This will be set to 0 upon a failed authentication attempt or an error during any other function.
lastauthtime	time	Stores the last epoch time when authentication was attempted.
success_reauth_time	time	Defines how long to wait to reauthenticate to VALT after a successful authentication.
failure_reauth_time	time	Defines how long to wait to reauthenticate to VALT after a failed authentication attempt.
errormsg	string	Last received error message.
testmsg	string	Result of a test connection to VALT
accesstoken	string	Stores the current access token obtained after successful authentication to VALT.
httptimeout	time	How long to wait for a result from an API call before assuming the VALT server is unreachable or unresponsive.
kill_threads	Boolean	Flag used to terminate threads running to monitor room status.
selected_room_status	int	Status of selected room. (0 = Failure, 1 = Available, 2 = Recording, 3 = Paused, 4 = Locked, 5 = Prepared, 99 = Valt Not Authenticated)
room_check_interval	time	How frequently to check the status of the selected room in seconds.
room_check_interval	time	How frequently to check the status of the selected room in seconds.
run_check_room_status	Boolean	Variable to determine if the room check should be run.

Parameters

valt(server,username,password)

Parameter	Type	Value	Required
server	String	IP address or DNS name of the Valt application server.	Yes
username	String	Valt Username.	Yes
password	String	Valt Password.	Yes
timeout	int	Timeout value in seconds. (see variables) Will default to 5 seconds if not specified.	no
logpath	string	Path to the log file, will default to ivs.log if not specified.	no
room	int	Room ID in valt to actively monitor and control. (Must be specified with room=)	no

Example

valt = ivs.valt("ivstest1.ad.ipivs.com","admin","admin")

auth

Usage

Connects to the Valt server. This function is executed automatically during initializaton.

Parameters

auth()

This function does not accept any parameters.

Example

valt.auth()

isrecording

Usage

Checks the state of a room and returns True if it is recording, or False if it is not. Returns 2 if an error is encountered.

Parameters

isrecording(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

if valt.isrecording(4):

getrecordingid

Usage

If the room is currently recording, it returns the ID of the active recording. You should check if the room is recording using the isrecording function prior to getting the recording ID.

Parameters

getrecordingid(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

current_recording = valt.getrecording(4)

startrecording

Usage

Starts a new recording in the specified room.

Parameters

startrecording(room,name,author)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes
name	String	The name that will be associated with the recording in Valt.	Yes
author	int	The user id under which the recording should be started. If not specified, the recording will be started under the authenticated user. Must be specified as author= when calling the function. See the example below.	No

Example

valt.startrecording(4,"My Recording",author=12)

stoprecording

Usage

Stops the current recording in the specified room.

Parameters

stoprecording(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

valt.stoprecording(4)

pauserecording

Usage

Pauses the current recording in the specified room.

Parameters

pauserecording(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

valt.pauserecording(4)

resumerecording

Usage

Unpauses the current recording in the specified room.

Parameters

resumerecording(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

valt.resumerecording(4)

WARNING

As of the writing of this article, pausing and unpausing the recording will reset the duration timer for the recording. This may cause issues with inserting markers.

addmarker

Usage

Adds a marker to the recording in progress in the specified room.

Parameters

addmarker(room,markername,color,markertime)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes
markername	String	Name for the marker in the Valt application.	Yes
color	String	Color for the marker, valid values are white, gray, red, yellow, purple, cyan, blue, green, and orange. If not specified, will default to red.	No
markertime	int	Time index to insert the marker. If not specified will use the current time index. When specifying a marker time, you must also specify a color.	No

Example

valt.addmarker(4,"My Marker","green",137)

WARNING

Markers only function in VALT 5.x and prior.

addcomment

Usage

Adds a comment to the recording in progress in the specified room.

Parameters

addmarker(room,markername,color,markertime)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes
markername	String	Name for the marker in the Valt application.	Yes
color	String	Color for the marker, valid values are white, gray, red, yellow, purple, cyan, blue, green, and orange. If not specified, will default to red.	No
markertime	int	Time index to insert the marker. If not specified will use the current time index. When specifying a marker time, you must also specify a color.	No

Example

valt.addmarker(4,"My Marker","green",137)

WARNING

Markers only function in VALT 6.x and above.

getrecordingtime

Usage

Returns the current time value of the recording in the specified room. Primarily used by the add marker function to specify the time for the marker.

Parameters

getrecordingtime(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

current_recording_time = valt.getrecordingtime(4)

ispaused

Usage

Checks the state of a room and returns True if it is paused, or False if it is not.

Parameters

ispaused(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

if valt.ispaused(4):

islocked

Usage

Checks the state of a room and returns True if it is locked and False if it is not.

Parameters

islocked(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

if valt.islocked(4):

getcameras

Usage

Returns a nested list, containing details for the cameras in the specified room.

Parameters

getcameras(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

cameras = valt.getcameras(4)

getrooms

Usage

Returns a list of rooms if successful. Each list item is actually a dictionary containing information about that room.

Parameters

getrooms()

This function does not accept any parameters.

Example

rooms = valt.getrooms()

getschedule

Usage

Returns a nested list of all upcoming schedules for the specified room. The returned list contains the start and end time for each schedule.

Parameters

getschedule(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

schedules = valt.getschedule(4)

getroomname

Usage

Returns the name of the room in VALT.

Parameters

getroomname(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

roomname = valt.getroomname(4)

getusername

Usage

Returns the name of the user in VALT.

Parameters

getusername(user)

Parameter	Type	Value	Required
user	Integer	The user number of the user in the Valt application. This must be the actual user ID number, not the user name. This can be obtained from the database.	Yes

Example

username = valt.getusername(4)

getroomstatus

Usage

Returns a value indicating the current status of the room. This should be used instead of islocked, ispaused, or isrecording as it also includes better error handling.

Room Status	Return Value
ERROR	0
Available	1
Recording	2
Paused	3
Locked	4
Prepared	5

Parameters

getroomstatus(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

roomstatus = valt.getroomstatus(4)

getusers

Usage

Function to return a list of users. Each list item is a dictionary with information about the user. Returns 0 on failure. Returns 99 if not currently authenticated to VALT.

Parameters

getusers()

This function does not accept any parameters.

Example

users = valt.getusers()

setsharing

Usage

Function changes/sets sharing permission on the specified recording. Users and groups must be passed as lists, encloded in []. Returns 0 on failure. Returns 99 if not currently authenticated to VALT.

Parameters

setsharing(recid,users=[],groups=[])

Parameter	Type	Value	Required
recid	Integer	The recording number of the record in the Valt application. This must be the actual record ID number, not the record name. This can be obtained from the database.	Yes
users	list	Comma separated list of users to be granted permission to the specified video. This must be the user ID number. This is an optional parameter and must be specified as users=[1,2,3,4].
No
groups	list	Comma separated list of groups to be granted permission to the specified video. This must be the groups ID number. This is an optional parameter and must be specified as groups=[1,2,3,4].	No

Example

valt.setsharing(176,users=[4,36,17,28],groups=[2,4])

lockroom

Usage

Locks the specified room.

Parameters

lockroom(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

valt.lockroom(4)

unlockroom

Usage

Unlocks the specified room.

Parameters

unlockroom(room)

Parameter	Type	Value	Required
room	Integer	The room number of the room in the Valt application. This must be the actual room ID number, not the room name. This can be obtained from the database.	Yes

Example

valt.unlockroom(4)

handleerror

Usage

Used for handling error results from other functions, such as return codes from VALT API calls. This function should not be called directly.

Parameters

handleerror(e)

Parameter	Type	Value	Required
e	string	Error code for handling.	Yes

reauthenticate

Usage

Schedules the next authentication attempt. Called after succeeding or failing an authentication attempt. Should not be called manually.

Parameters

unlockroom(room)

Parameter	Type	Value	Required
reauthtime	Integer	The number of seconds in the future to scheduled the next authentication attempt.	Yes

changeserver

Usage

Connects the VALT class to a different VALT server.

Parameters

changeserver(address,username,password)

Parameter	Type	Value	Required
valt_address	String	The url for new VALT server.	Yes
valt_username	String	The username for new VALT server.	Yes
valt_password	String	The password for new VALT server.	Yes

Example

valt.changeserver("https://demo.valt.video","admin","admin")

testconnection

Usage

Tests url and credentials supplied to connect to a valt server without actually changing the server the class is actually connected to.

Parameters

testconnection(address,username,password)

Parameter	Type	Value	Required
valt_address	String	The url for new VALT server.	Yes
valt_username	String	The username for new VALT server.	Yes
valt_password	String	The password for new VALT server.	Yes

Example

valt.testconnection("https://demo.valt.video","admin","admin")

getrecords

Usage

Returns a dictionary with all recordings that match the provided search criteria.

Parameters

getrecords(**kwargs)

Parameter	Type	Value	Required
search	String	Searches metadata for the provided value. Must be specified as search="search terms"	No
start_date	Date	Returns only results recorded on or after the specified date. Must be specified as start_date="date"	No

Example

valt.getrecords(search="Test")

getversion

Usage

Returns the current version of VALT.

Parameters

None

Example

valt.getversion()

check_room_status

Usage

Loop to check specified room status every X seconds. Started in a thread automatically when a room is specified. Should not be run manually.

start_room_check_thread

Usage

Initiates the room check thread. Should not be run manually.

stop_room_check_thread

Usage

Stop room check thread. Should not be run manually.

change_timeout

Usage

Adjusts the timeout value for response from VALT.

Parameters

change_timeout(new_timeout)

Parameter	Type	Value	Required
new_timeout	Integer	Number of seconds to wait for a response from VALT before assuming it is unavailable or nonresponsive.	Yes

Example

valt.change_timeout(10)

disconnect

Usage

Terminates running threads and disconnects from active VALT session. Can be run just prior to ending program or when instantiating a new instance of the VALT class.

Example

valt.disconnect()