Synchronize, disable, and delete channels

A channel is the video resource users ultimately see and operate. Playback, recording, permissions, and external systems all locate it by a stable channel ID, so rename, offline, disable, and delete are not the same operation.

Start with the state diagram

stateDiagram-v2
    direction LR
    [*] --> Enabled: Add or synchronize
    Enabled --> Offline: Device or network failure
    Offline --> Enabled: Device recovers
    Enabled --> Disabled: Operator disables
    Disabled --> Enabled: Re-enable
    Disabled --> Deleted: Dependencies confirmed absent

• Online/offline is an observed runtime state and should not be fabricated manually.
• Enable/disable controls whether new playback, recording, or control operations can start; history remains.
• Rename changes visible text but should not change the channel ID.
• Delete can affect dependent business data and is normally the last choice.

Synchronize channels for the first time

1. Find the newly added device and run Synchronize channels or Refresh catalog.
2. Wait for the task to finish, then open the device channel list.
3. Check the count, names, primary/sub streams, and protocol identity such as an ONVIF Profile token or GB28181 DeviceID.
4. Preview a sample channel to prove that synchronization did not create only an empty named record.

Test one device before a bulk sync, especially for multi-channel NVRs and large GB28181 catalogs. Later syncs must match existing channels by stable protocol identity; a name or order change must not create duplicates.

Enable or disable PTZ control

Open Asset details → Channel configuration → PTZ control, inspect the reported device capability, change Allow PTZ control, and click Save PTZ settings. This saves only the PTZ policy; no restart is required and playback, audio, and recording are unchanged.

• GB28181 uses the Catalog received after registration, including nested Info/PTZType. Registration or the protocol name alone does not prove PTZ support. Fixed, missing, and unknown types do not enable controls by default.
• ONVIF uses the Profile PTZConfigurationToken; an ordinary video Profile is not automatically a PTZ Profile.
• Reported capability and operator permission are separate. A capable device can be disabled; allowing an incapable device does not invent support. Catalog/Profile refresh and device reconnection do not reset the operator switch.
• Disabling hides the panel and rejects new operations through unified channel control and registered protocol PTZ entry points. Stop commands remain available to safely end motion; disabling does not retract commands already dispatched.
• A failed save retains the draft. Read the settings again to confirm the stored value. Changing the policy requires channels.manage; operating the device still requires devices.control.

Use GET /api/v2/channels/{channelId}/ptz/settings and PUT /api/v2/channels/{channelId}/ptz/settings. Submit {"enabled": false} or {"enabled": true}. The response separates reported, enabled, and effective canControl. For legacy configurations, use the effective capability returned by the API.

For snapshot settings, queries, and downloads, see the dedicated periodic snapshot guide.

When a channel should be temporarily unavailable

Choose Disable instead of Delete. A disabled channel should reject new streams while keeping recordings and audit history. Re-enable it when service should resume.

An enabled channel consumes license capacity. When capacity is full, adding or re-enabling is rejected; disabling, stopping streams, and cleanup remain available so capacity can be released. Do not bypass this rule by editing the database.

Decide which name is authoritative before renaming

After renaming, open historical recordings and the integrated business flow to confirm that relationships remain intact.

Run 5 checks before deletion

1. Are there active streams, recording sessions, or unfinished control commands?
2. Are recordings, schedules, alarms, favorites, or external mappings linked?
3. Is the device only temporarily offline and expected to report again?
4. Is this a recoverable soft delete or an irreversible hard delete?
5. Have required audit and business records been retained?

For a bulk action, inspect per-item results and retry only failed items. Do not repeat successful operations merely because the overall batch is marked failed.

Acceptance check

• One physical channel has one platform channel ID.
• Device restart, rename, and repeated sync do not create duplicate channels.
• Disable blocks new business operations while historical recordings remain searchable.
• Deletion follows the retention rules for recordings, audit, and external mappings.