APIs: utils

Get Channel List

Retrieve the list of camera channels.

🛠️ channels = get_channel_list()

↩️ channels: An array of objects containing channel information. Each object includes the following properties:

🔹ch_no: Channel number.

🔹title: Channel title.

🔹is_connected: Indicates whether the camera is connected.

🔹is_recording: Indicates whether the camera is recording.

🔹is_ptz: Indicates whether the camera is a PTZ (Pan-Tilt-Zoom) camera.

🔹ptz_presets: A list of PTZ presets, where "no" is the preset number and "title" is the preset title.

🔹date_start: Recording start date in the string format "yyyy-mm-dd".

🔹date_end: Recording end date in the string format "yyyy-mm-dd".

🔹sub_channel_count: The number of sub-channels.

utils = vmspy.utils()
if not utils.init(address, port, access_id, access_pw):
    print(utils.get_error())

channels = utils.get_channel_list()
for ch in channels:
    print("Ch No:", ch.ch_no)       # 1
    print("Title:", ch.title)       # "Channel Title"
    print("Sub Channels:", ch.sub_channel_count) # 0
    print("Connected:", ch.is_connected) # True/False
    print("Recording:", ch.is_recording) # True/False
    print("Start:", ch.date_start)  # "2025-04-01"
    print("End:", ch.date_end)      # "2025-04-17"
    print("PTZ:", ch.is_ptz)        # True
    for p in ch.ptz_presets:
        print("-Preset No:", p.no)        # 1
        print("-Preset Title:", p.title)  # "Preset#1"

Get Group List

Retrieve the group list along with their member channels.

🛠️ groups = get_group_list()

↩️ groups: An array of objects containing group information. Each object includes the following properties:

🔹group_idx: Index of the group.

🔹title: Title of the group.

🔹channels: An array of objects containing channel information.

🔹ch_no: Channel number.

🔹title: Channel title.

utils = vmspy.utils()
if not utils.init(address, port, access_id, access_pw):
    print(utils.get_error())

groups = utils.get_group_list()
print(group_list)

for gr in groups:
    print("Group index:", gr.idx)  # 0
    print("Title:", gr.title)     # "Group Title"
    for ch in gr.channels:
        print("- ch no:", ch.ch_no) # 1
        print("- title:", ch.title) # "Channel Title"

Get Recording Dates

Retrieve the recording dates for a specified month.

🛠️ dates = get_recording_dates(year, month)

➡️ year, month: Specify the month to request.

↩️ dates: An array of objects. Each object includes:

🔹ch_no: Channel number.

🔹title: Channel title.

🔹dates: An array of days with recordings, e.g., ["2026-03-19", "2026-03-20"].

utils = vmspy.utils()
if not utils.init(address, port, access_id, access_pw):
    print(utils.get_error())

recordingDates = utils.get_recording_dates(2026, 3)
for rcd in recordingDates:
    print("Channel No:", rcd.ch_no)     # 1
    print("Channel Title:", rcd.title)  # "Channel Title"
    for ds in rcd.dates:
        print("- Date:", ds)            # "2026-03-19"

Get Recording Times

Retrieve the recording times for a specific date.

🛠️ recording_times = get_recording_times(ch_no, year, month, day, sub_idx=0)

➡️ ch_no: Channel number.

➡️ year, month, day: Specify the recording date to request.

➡️ sub_idx: Channel sub_idx, zero (0) for primary.

↩️ recording_times: An array of objects. Each object includes the following properties:

🔹time: Start time of recording in ISO-8601 format.

🔹timestamp: Start time of recording as a Unix timestamp.

🔹is_dst: Indicates whether the time is in DST.

🔹duration: Duration of recording in seconds.

recordingTimes = utils.get_recording_times(1, 2025, 4, 18) # ch#1
for t in recordingTimes:
    print("Time:", t.time)            # 2026-03-20T11:22:45+09:00
    print("Timestamp:", t.timestamp)  # 1773973365
    print("DST:", t.is_dst)           # False
    print("Duration:", t.duration)    # 171

Get Archived Files

Retrieve the list of archived files.

🛠️ files = get_file_list()

↩️ files: An array of objects. Each object includes the following properties:

🔹file_id: File ID.

🔹ch_no: Channel number.

🔹title: Channel title.

🔹time: File start time in ISO 8601 format.

🔹timestamp: File start time as a Unix timestamp.

🔹is_dst: Indicates whether the time is in DST.

🔹duration: File duration in seconds.

🔹priority: File priority (0–5).

🔹filesize: File size of the file.

utils = vmspy.utils()
if not utils.init(address, port, access_id, access_pw):
    print(utils.get_error())

files = utils.get_file_list()
for file in files:
    print("File ID:", file.file_id)     # 29513186
    print("Channel No:", file.ch_no)    # 1
    print("Channel Title:", file.title) # "Channel Title"
    print("Time:", file.time)           # 2026-02-11T15:23:17+09:00
    print("Timestamp:", file.timestamp) # 1770790997
    print("DST:", file.is_dst)          # False
    print("Duration:", file.duration)   # 16
    print("Priority:", file.priority)   # 0
    print("File size:", file.filesize)  # 11408614471

Get Events

Retrieve events for a specific date and channel(s).

🛠️ events = get_events(ch_no, year, month, day, num_days=1)

➡️ ch_no: Channel number. If set to zero (0), events for all channels are retrieved.

➡️ year, "month", "day": Specify the date to request.

➡️ num_days: Specifies the number of days for which events should be returned (default: 1).

↩️ events: An array of objects. Each object includes the following properties:

🔹ch_no: Channel number of the event.

🔹type: Type of the event.

🔹time: Time of the event in ISO-8601 format.

🔹timestamp: Time of the event as a Unix timestamp.

🔹is_dst: Indicates whether the time is in DST.

🔹duration: Duration of the event in seconds.

utils = vmspy.utils()
if not utils.init(address, port, access_id, access_pw):
    print(utils.get_error())

events = utils.get_events(0, 2025, 4, 18, num_days=5) # For all channels over 5 days
for e in events:
    print("Channel No:", e.ch_no)     # 1
    print("Event Type:", e.type)      # "MOTION"
    print("Time:", e.time)            # 2026-03-20T11:22:45+09:00
    print("Timestamp:", e.timestamp)  # 1773973365
    print("DST:", e.is_dst)           # False
    print("Duration:", e.duration)    # 11

Move PTZ Preset Position

Move the PTZ camera to a specified preset position.

🛠️ ptz_preset_go(ch_no, preset_no)

➡️ ch_no: Channel number.

➡️ preset_no: The preset number to move the camera to.

if not utils.ptz_preset_go(1, 3):
    print(utils.get_error())

Get PTZ Preset Position

Retrieve the current PTZ camera preset position.

🛠️ preset = get_ptz_preset(ch_no)

➡️ ch_no: Channel number.

↩️ preset: Returns `None` if no preset position is set for the channel, or an object with the following properties:

🔹no: The preset number.

🔹title: The preset title.

p = utils.get_ptz_preset(1)
if p == None:
    print("No prest position is set")
else:
    print(f"Preset position #{p.no}.{p.title} is set")

Show Live Channel on VMS server

Display the live video image of the channel on a VMS server.

🛠️ show_live(ch_no, sub_idx=0)

➡️ ch_no: Channel number.

➡️ sub_idx: Channel sub_idx, zero (0) for primary.

if not utils.show_live(1):
    print(utils.get_error())

Show Playback Channel on VMS server

Display the playback video image of the channel at the specified time on a VMS server.

🛠️ show_playback(ch_no, year, month, day, hour, minute, second, sub_idx=0)

➡️ ch_no: Channel number.

➡️ year, month, day: Specify the playback date.

➡️ hour, minute, second: Specify the playback time.

➡️ sub_idx: Channel sub_idx, zero (0) for primary.

if not utils.show_playback(1, 2025, 4, 18, 14, 30, 0):
    print(utils.get_error())

Show Group Live on VMS server

Display the live video images of a specified group on a VMS server.

🛠️ show_group_live(group_idx)

➡️ group_idx: The index of the group.

# Display the first group (group_idx=0) in the VMS
if not utils.show_group_live(0):
    print(utils.get_error())

Show Group Playback on VMS server

Display the playback video images of a specified group at a given time on a VMS server.

🛠️ show_group_playback(group_idx, year, month, day, hour, minute, second)

➡️ group_idx: The index of the group.

➡️ year, month, day: Specify the playback date.

➡️ hour, minute, second: Specify the playback time.

# Display the first group (group_idx=0) at 2025-04-18 14:30:00 in the VMS
if not utils.show_group_playback(0, 2025, 4, 18, 14, 30, 0):
    print(utils.get_error())

Show Archived File Playback on VMS server

Display the playback video images of a specified group at a given time on a VMS server.

🛠️ show_file_playback(file_id, timestamp)

➡️ file_id: Specify the file ID.

➡️ timestamp: Specify the playback time as a Unix timestamp.

# Display the archived file (file_id=29513186) at the unix timestamp 1770790997
if not utils.show_file_playback(29513186, 1770790997):
    print(utils.get_error())