Skip to main content
The file watcher system automatically monitors incoming directories for each device and processes new media files as they arrive. The system provides automatic management with manual control when needed.

​
Automatic management

File watchers are automatically managed by the Studio service:
  • Auto-initialization - Watchers are created for all devices on service startup
  • Periodic sync - Watchers sync with the device list every 5 minutes
  • Graceful cleanup - Orphaned watchers are cleaned up when devices are deleted
  • Error recovery - Watchers are automatically restarted if they encounter errors

​
Get watcher status

GET /api/watchers

Get status of all file watchers

​
Response

​
watchers
array
required
Array of watcher status objects
​
watchers[].deviceId
string
Device identifier
​
watchers[].active
boolean
Whether the watcher is currently active
​
watchers[].path
string
Path being monitored
​
watchers[].lastActivity
string
ISO 8601 timestamp of last file detection

​
Example request

curl "http://localhost:8001/api/watchers" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "watchers": [
    {
      "deviceId": "device123",
      "active": true,
      "path": "/data/gallery/device123/incoming",
      "lastActivity": "2024-03-20T10:30:00Z"
    },
    {
      "deviceId": "device456",
      "active": true,
      "path": "/data/gallery/device456/incoming",
      "lastActivity": null
    }
  ]
}

​
Check device watcher status

GET /api/watchers/:deviceId/status

Check if a specific device has an active watcher

​
Path parameters

​
deviceId
string
required
Device identifier

​
Response

​
active
boolean
required
Whether the watcher is active for this device
​
deviceId
string
required
Device identifier
​
path
string
Path being monitored (if active)

​
Example request

curl "http://localhost:8001/api/watchers/device123/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "active": true,
  "deviceId": "device123",
  "path": "/data/gallery/device123/incoming"
}

​
Add watcher

POST /api/watchers/:deviceId/add

Add a file watcher for a specific device

​
Path parameters

​
deviceId
string
required
Device identifier

​
Response

​
success
boolean
required
Indicates if the watcher was added successfully
​
deviceId
string
required
Device identifier

​
Example request

curl -X POST "http://localhost:8001/api/watchers/device123/add" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "deviceId": "device123"
}

​
Remove watcher

DELETE /api/watchers/:deviceId

Remove the file watcher for a specific device

​
Path parameters

​
deviceId
string
required
Device identifier

​
Response

​
success
boolean
required
Indicates if the watcher was removed successfully
​
deviceId
string
required
Device identifier

​
Example request

curl -X DELETE "http://localhost:8001/api/watchers/device123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "deviceId": "device123"
}

​
Sync watchers

POST /api/watchers/sync

Synchronize watchers with the current device list

​
Description

This endpoint:
  • Adds watchers for devices that don’t have one
  • Removes watchers for devices that no longer exist
  • Ensures all active devices are being monitored

​
Response

​
success
boolean
required
Indicates if synchronization was successful
​
added
number
Number of watchers added
​
removed
number
Number of watchers removed

​
Example request

curl -X POST "http://localhost:8001/api/watchers/sync" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "added": 2,
  "removed": 1
}

​
Refresh watchers

POST /api/watchers/refresh

Restart all file watchers

​
Description

Useful after configuration changes or to recover from errors. This endpoint:
  • Stops all active watchers
  • Restarts watchers for all devices
  • Reloads configuration

​
Response

​
success
boolean
required
Indicates if refresh was successful
​
count
number
Number of watchers restarted

​
Example request

curl -X POST "http://localhost:8001/api/watchers/refresh" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "count": 5
}

​
Clean up orphaned watchers

POST /api/watchers/cleanup-orphaned

Manually clean up watchers for deleted devices

​
Description

Removes watchers for devices that no longer exist in the database. This is automatically done during periodic sync, but can be triggered manually.

​
Response

​
success
boolean
required
Indicates if cleanup was successful
​
removed
number
Number of orphaned watchers removed

​
Example request

curl -X POST "http://localhost:8001/api/watchers/cleanup-orphaned" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "removed": 3
}

​
File watcher behavior

​
Detection

When a file watcher detects a new file in the incoming directory:
  1. File detection - New file appears in incoming directory
  2. Metadata extraction - File size, type, and name are determined
  3. Gallery record creation - Database record is created
  4. Thumbnail processing - Checks for matching thumbnail file
  5. File movement - Moves file from incoming to processed directory
  6. Hook execution - Triggers on_file_detected hooks

​
Monitoring

File watchers monitor the incoming directory continuously and:
  • Detect new files immediately
  • Handle multiple files concurrently
  • Skip temporary and hidden files
  • Process files atomically to avoid race conditions

​
Error handling

If a watcher encounters an error:
  • Error is logged with details
  • Watcher attempts automatic recovery
  • on_error hooks are triggered
  • Problematic files are quarantined

Build docs developers (and LLMs) love

Get started for freeTalk to us