Recording import / migration

[samuelwei]

Is your feature request related to a problem? Please describe.
Recording that exists in other systems, directly on a BBB Server or on a BBB Load-Balancer (Scalelite, B3Scale, BBBLB, etc.), cannot be used within PILOS.

PILOS doesn't follow the BBB ecosystems common solution to recording handling, where the frontend is just providing a link to the recordings location. This is due to it's dual nature of being a frontend and load balancer in it self, and also to provide a way more detailed and secure recording access policy.

Describe the solution you'd like
Command and/or guide how to import / transfer recordings from third party systems.

Describe alternatives you've considered
none

Additional context
none

[pizkaz]

#3034 implements this for Greenlight 2 / Greenlight 3 migrations by creating a hidden (as in: no start/end timestamp) meeting for every imported room. This way, recordings can be correctly associated with the right (imported) room, so all you need to do is find the relevant recordings, pack tar files and put them in the recordings-spool directory.

[samuelwei]

@pizkaz We still have to take care of the recording visibility.

[samuelwei]

How about creating CLI Tools:

PILOS Command: export:meeting-ids

Purpose

Generate a list of all meetings IDs

Note: These meeting IDs will contain all PILOS originated meetings as well as GL 2/3 BBB IDs. This list will be very long for an existing PILOS installation. On a fresh PILOS server with data migrated from GL2/3 it should only contain one meeting for room with the ID of BBB Meeting ID of each room.

CLI Tool: bbb-recording-exporter

Purpose

Export recordings from BigBlueButton (BBB) or a BBB-LB, optionally based on a list of meeting IDs.
The tool fetches recording metadata via the BBB API and stores them as .tar archives.

---

Execution Context

• Runs on a BBB-Server or BBB Load Balancer
• Requires network access to BBB API endpoint

---

Inputs / Parameters

1. API Configuration

• --api-url
  Base URL of BBB API (e.g. https://bbb.example.com/bigbluebutton/api)

• --api-secret
  Shared secret used for API authentication

---

2. Input Data

• --meeting-id-file (Optional)
  Path to file containing BBB meeting IDs (one per line)

---

3. Recording Source Paths

(Define where recordings are located on disk; placeholders are resolved per recording)

• --published-path-template
  Example: /var/bigbluebutton/published/{format}/{internalMeetingID}

• --unpublished-path-template
  Example: /var/bigbluebutton/unpublished/{format}/{internalMeetingID}

Allowed placeholders: format, internalMeetingID, recordingID, meetingID

---

4. Output Paths

• --output-published-dir
  Directory where .tar archives of published recordings are stored

• --output-unpublished-dir
  Directory where .tar archives of unpublished recordings are stored

---

Core Workflow

1. Read Meeting IDs if file is passed

   • Parse input file
   • Validate format / remove duplicates

2. Fetch Recording Metadata

   • Call BBB API (getRecordings) for each meeting ID

   • Parameter

     • meetingID: meeting ID (if file is provided)
     • state: published,unpublished

   • Extract:

     • recordingID
     • internalMeetingID
     • meetingID
     • formats (e.g. presentation, video, etc.)
     • state (published/unpublished)

3. Resolve File Paths

   • Select template based on published flag

   • Replace placeholders:

     • {recordingID}
     • {internalMeetingID}
     • {meetingID}
     • {format}

4. Validate Source Directory

   • Check existence
   • Log missing recordings (do not crash entire run)

5. Archive Recording

   • Create .tar file:

     <recordingID>.tar
     

   • Include all files in the resolved directory

6. Store Archive

   • Move .tar to:

     • published or unpublished output directory

7. Logging & Reporting

   • Summary:

     • total recordings processed
     • succeeded / failed / missing

Example Command

bbb-recording-exporter \
  --api-url https://bbb.example.com/bigbluebutton/api \
  --api-secret XXX \
  --meeting-id-file meetings.txt \
  --published-path-template "/var/bigbluebutton/published/{format}/{internalMeetingID}" \
  --unpublished-path-template "/var/bigbluebutton/unpublished/{format}/{internalMeetingID}" \
  --output-published-dir /exports/published \
  --output-unpublished-dir /exports/unpublished