How-To Guides

Common Tasks

This section provides practical guides for common NPVR operations.

Creating a Recording

To create a new NPVR recording, send a POST request to the management API:

curl -X POST http://localhost:8099/api/v1/content \
  -H "Content-Type: application/json" \
  -d '{
    "channelName": "channel-1",
    "title": "Evening News",
    "startTime": 1713268800,
    "stopTime": 1713272400,
    "refID": "news-2026-04-16"
  }'

Response:

{
  "id": "01HP2Q3R4S5T6U7V8W9X0Y1Z2"
}

Save the returned id for future operations on this recording.

Listing Recordings

List all recordings:

curl http://localhost:8099/api/v1/content

List recordings for a specific channel:

curl "http://localhost:8099/api/v1/content?channel=channel-1"

List recordings in a time range:

curl "http://localhost:8099/api/v1/content?channel=channel-1&startTime=1713268800&stopTime=1713355200"

List with pagination:

# First page
curl "http://localhost:8099/api/v1/content?channel=channel-1&limit=100"

# Next page (use cursor from response)
curl "http://localhost:8099/api/v1/content?cursor=eyJjaGFubmVs..."

Getting Recording Details

By database ID:

curl "http://localhost:8099/api/v1/content/01HP2Q3R4S5T6U7V8W9X0Y1Z2"

By reference ID:

curl "http://localhost:8099/api/v1/content?id=news-2026-04-16"

Updating a Recording

To extend or shorten a recording, update its start and end times:

curl -X PUT http://localhost:8099/api/v1/content/01HP2Q3R4S5T6U7V8W9X0Y1Z2 \
  -H "Content-Type: application/json" \
  -d '{
    "id": "01HP2Q3R4S5T6U7V8W9X0Y1Z2",
    "startTime": 1713268800,
    "stopTime": 1713276000
  }'

Note: Recording can only be updated if it’s in an allowed state (pending, done, or error).

Deleting a Recording

curl -X DELETE "http://localhost:8099/api/v1/content/01HP2Q3R4S5T6U7V8W9X0Y1Z2"

The entry will be marked with state deleting and removed asynchronously.

Checking Recording State

After creating a recording, check its state periodically:

# Get recording details
curl "http://localhost:8099/api/v1/content/01HP2Q3R4S5T6U7V8W9X0Y1Z2" | jq '.entries[0].state'

Possible states:

• pending: Waiting to start
• ongoing: Recording in progress
• done: Completed successfully
• error: Failed with error
• updating: Being updated
• deleting: Being deleted

Working with Reference IDs

Reference IDs allow you to use your own identifiers instead of database-generated UUIDs.

Create with reference ID:

curl -X POST http://localhost:8099/api/v1/content \
  -H "Content-Type: application/json" \
  -d '{
    "channelName": "channel-1",
    "title": "My Show",
    "startTime": 1713268800,
    "stopTime": 1713272400,
    "refID": "show-s01e05"
  }'

Retrieve using reference ID:

curl "http://localhost:8099/api/v1/content?id=show-s01e05"

Note: Reference IDs must be unique across all recordings.

Monitoring Service Health

Check management API health:

curl http://localhost:8099/

Check media API health (if using TCP):

curl http://localhost:8080/

View service logs:

# General logs
tail -f /var/log/edgeware/ew-npvr/ew-npvr.log

# Streaming logs
tail -f /var/log/edgeware/ew-npvr/ew-npvr-streaming.log

# Admin logs
tail -f /var/log/edgeware/ew-npvr/ew-npvr-admin.log

# System journal
journalctl -u ew-npvr -f

Using the Swagger UI

Interactive API documentation is available at:

http://localhost:8099/swagger/

This provides:

• Complete API reference
• Try-it-out functionality
• Request/response examples
• Schema definitions

Configuring Storage Locations

Add a new storage location in the configuration:

{
  "storage": {
    "npvr": {
      "locations": [
        {
          "name": "fast-storage",
          "basePath": "/mnt/ssd/npvr",
          "copyBehavior": "copy"
        },
        {
          "name": "archive-storage",
          "basePath": "/mnt/hdd/npvr",
          "copyBehavior": "hard-link"
        }
      ]
    }
  }
}

Then assign channels to storage locations:

{
  "services": {
    "liveIngest": {
      "channels": [
        {
          "name": "news-channel",
          "npvrLocation": "fast-storage"
        },
        {
          "name": "movies-channel",
          "npvrLocation": "archive-storage"
        }
      ]
    }
  }
}

Troubleshooting

Recording stays in “pending” state:

• Check that the channel exists and is running in live ingest
• Verify the start time hasn’t already passed
• Check channel configuration and NPVR location assignment
• Review logs: journalctl -u ew-npvr -n 100

Recording in “error” state:

• Check available disk space on storage location
• Verify source segments are available from live ingest
• Review logs for specific error messages
• Check file permissions on storage path

Cannot create recording (424 error):

• Verify channel is producing segments
• Check that requested time range has available segments
• Ensure live ingest is running and accessible

Database connection fails:

• Service continues in degraded mode
• Management API will not be available
• Media API still works for existing content
• Check PostgreSQL connectivity and credentials

Playable remains false:

• Recording may still be processing
• Check storage path for actual files
• Wait for state to change to “done”
• Review logs for processing errors