Dateien

Verwenden Sie Dateien, um hochgeladene, aufgezeichnete und verarbeitete Medien zu verwalten. Registrieren Sie eine Datei, erstellen Sie eine abgeleitete Version, kopieren Sie sie in ein konfiguriertes Speicherziel oder entfernen Sie sie.

FunktionMediendatei verwalten

Geeignet, wennMedien liegen bereits als Datei vor und sollen hochgeladen, verarbeitet, kopiert oder gelöscht werden.

Anderes Modul verwenden, wennVerwenden Sie Aufzeichnungen für Live-Quellen; Speicherziele registrieren lediglich das externe Ziel.

1Datei hinzufügen oder finden2Bei Bedarf verarbeiten3Wiederverwenden oder exportieren

POST /api/files/create

Endpunkte filtern11 Endpunkte

Voraussetzungen

Alle Methoden erfordern einen gültigen x-access-token. Die Instanz benötigt genügend lokalen Speicherplatz für Upload und Verarbeitung. Für das Kopieren in einen Objektspeicher muss außerdem ein Speicherziel konfiguriert sein.

Funktionen

upload und create fügen eine Mediendatei hinzu.
getAll, getCount und getById prüfen das Dateiinventar.
update ändert unterstützte Dateimetadaten.
copyTo startet eine Speicherkopie und getCopyProgress meldet den Fortschritt.
getStat liest den Status der verfügbaren Verarbeitung.
remove oder removeByPath löscht eine Mediendatei.

Beispiel-Workflow

Laden Sie einen kurzen Testclip hoch und behalten Sie die zurückgegebene Dateikennung bei.
Erstellen Sie die benötigte abgeleitete Version oder aktualisieren Sie deren Metadaten.
Starten Sie copyTo für ein konfiguriertes Archivziel.
Rufen Sie getCopyProgress regelmäßig ab, bis die Übertragung abgeschlossen ist.
Überprüfen Sie das Archiv, bevor Sie die lokale Datei entfernen.

Typische Anwendungsfälle

Verschieben Sie abgeschlossene Ereignisaufzeichnungen in den Objektspeicher.
Erstellen Sie aus einer hochgeladenen Masterdatei eine für die Wiedergabe vorbereitete Version.
Bereinigen Sie lokale Medien, nachdem Aufbewahrungs- und Archivprüfungen erfolgreich abgeschlossen wurden.

Einschränkungen und Fehlerbehebung

Große Uploads und Kopien laufen asynchron und können wegen unzureichenden Speicherplatzes, falscher Zugangsdaten, zu geringer Netzwerkkapazität oder eines ungültigen Pfads fehlschlagen. Entfernen Sie die Quelle erst, nachdem Sie das Ziel geprüft haben. Behandeln Sie von Benutzern übermittelte Pfade und Dateinamen als nicht vertrauenswürdige Eingaben.

Nächste Schritte

Konfigurieren Sie Speicherziele für eine dauerhafte Aufbewahrung oder Webplayer, wenn die Mediendatei für die Browser-Wiedergabe bereitgestellt werden soll.

REST-Lösungsrezept

Eine Mediendatei verarbeiten und in Storage kopieren

Erstellen oder laden Sie die verwaltete Datei hoch, überwachen Sie die Verarbeitung und kopieren Sie das fertige Objekt in ein konfiguriertes Speicherziel.

Verwaltetes Derivat erstellenWählen Sie Quelle, Ausgabeformat und benötigte Verarbeitung.POST /api/files/create
Verarbeitung überwachenWarten Sie auf den Abschluss des Hintergrund-Workers.POST /api/files/getStat
In Storage kopierenSenden Sie die fertige Datei an ein registriertes Ziel.POST /api/files/copyTo
Kopierabschluss prüfenBehalten Sie die Quelle bis zur bestätigten Fertigstellung.POST /api/files/getCopyProgressById

Entfernen Sie die Quelle erst, wenn Verarbeitung und Kopie abgeschlossen und das Zielobjekt geprüft sind.

POST

/api/files/create

API-Token erforderlich

Diese Methode legt im Dateimanager einen verwalteten Dateieintrag an. Damit wird eine hochgeladene Datei zu einer zuverlässig nutzbaren Ressource: als benannte Datei, konvertierte Ausgabe oder wiederverwendbare Wiedergabe- beziehungsweise Overlay-Datei.

Der Aufruf speichert nicht nur Metadaten. Wenn das angeforderte output_format oder die Transcodierungsoptionen von der hochgeladenen Datei abweichen, kann Callaba die erforderliche Konvertierung unmittelbar starten.

Beispiele nach Voreinstellung zeigen die wichtigsten Varianten: eine hochgeladene MP4 unverändert übernehmen, eine MP3-Ausgabe erzeugen oder ein HLS-Paket erstellen.

Direkte Dateiregistrierung

Verwenden Sie diese Voreinstellung, wenn eine hochgeladene Masterdatei ohne zusätzliche Konvertierung zu einer wiederverwendbaren verwalteten Mediendatei werden soll.

Hochgeladene MP4-Datei

Dies ist der sauberste Dateimanager-Ablauf: Laden Sie zuerst hoch, registrieren Sie anschließend die Datei mit Metadaten und Sichtbarkeit als dauerhaften Dateieintrag.

Hochgeladene MP4-Datei

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Speichern und Konvertieren

Verwenden Sie diese Voreinstellung, wenn die gespeicherte Datei bei der Verarbeitung in ein einfacheres Audio umgeschrieben werden soll.

Hochgeladene Datei als MP3-Version

Der Dateieintrag wird zuerst erstellt, dann erzeugt der Hintergrund-Transcoding-Worker die abgeleitete Datei und zeigt den Fortschritt durch getStat an.

Hochgeladene Datei als MP3-Version

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage audio extract",
  "file_visibility": "private",
  "file_description": "Audio-only derivative prepared from the uploaded mezzanine file.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp3",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "mp3",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Segmentierte Ausgabe

Verwenden Sie diese Voreinstellung, wenn die resultierende Mediendatei als HLS-Paket anstelle einer einzelnen Datei erzeugt werden soll.

Hochgeladene Datei als HLS-Paket

Dies ist nützlich, wenn die verwaltete Datei an einen Wiedergabe- oder Bereitstellungsworkflow übergeben wird, der eine HLS-ähnliche Verzeichnisausgabe erwartet.

Hochgeladene Datei als HLS-Paket

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage HLS package",
  "file_visibility": "private",
  "file_description": "Segmented HLS output prepared from an uploaded mezzanine file.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "m3u8",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "h264",
    "audio_transcoding": "aac",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Parameter im Request-Body

Identität

file_name

string

Dashboard-Bezeichnung: Name.

Benutzerfreundlicher Name der Datei im Dateimanager.

Dateipfad

file_path

string

Dashboard-Bezeichnung: Datei.

Pfad, der von uploadFile erzeugt wurde oder der Plattform bereits bekannt ist.

file_unique_id

string

Korrelations-ID, die einen laufenden Upload mit dem gespeicherten Dateieintrag verknüpft.

Richtlinie

file_visibility

string

Dashboard-Bezeichnung: Sichtbarkeit.

Kontrolliert, ob die gespeicherte Datei in nachgelagerten UI-Flows als öffentlich oder privat behandelt werden soll.

file_description

string

Optionale Beschreibung, die im Dateieintrag gespeichert ist.

Verarbeitung

output_format

string

Dashboard-Bezeichnung: Ausgabeformat.

Wenn das angeforderte Format von der hochgeladenen Erweiterung abweicht, startet das Backend einen Hintergrundprozess zur Formatumwandlung.

transcoding

object

Optionale Transcodierungseinstellungen, die verwendet werden, wenn die Datei in ein anderes Ausgabeformat konvertiert werden soll.

Kontext

module_name

string

Optionaler Quellkontext für UI-gesteuerte Abläufe. In der Praxis speichert der Dateimanager üblicherweise Einträge unter MODULE_FILES.

Datei erstellen

curl --request POST \
  --url http://localhost/api/files/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  }
}'

Antwort

Identität

_id / id / file_name

mixed

Gespeicherte Dateibezeichner und der persistente Dateiname.

Dateipfad

file_path / file_unique_id

mixed

Speicherort der Datei plus Upload-Korrelations-ID.

Richtlinie

file_visibility / file_description

mixed

Gespeicherte Sichtbarkeit und beschreibende Metadaten für die Mediendatei.

Verarbeitung

output_format / transcoding / overlay

mixed

Ausgabeformat und Verarbeitungszustand, der mit dem Dateieintrag gespeichert ist.

Laufzeit

size_bytes / duration_ms / created

mixed

Berechnete Medienmetriken und Backend-verwaltete Zeitstempelfelder.

Antwort: Datei erstellen

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/uploadFile

API-Token erforderlich

POST

/api/files/getCount

API-Token erforderlich

POST

/api/files/getAll

API-Token erforderlich

Rufen Sie mit dieser Methode alle für den aktuellen Filter sichtbaren Dateieinträge ab. Die Liste dient als Inventar für wiederverwendbare Mediendateien, erzeugte Ausgaben und Aufzeichnungen, die weiterhin von Callaba verwaltet werden.

Parameter im Request-Body

limit

integer

Optionale Seitengröße für Dateimanager-Auflistungsabfragen.

skip

integer

Optionaler Offset für die paginierte Dateiliste.

sort

object

Optionale Sortierdefinition. Das Dashboard ist standardmäßig { created: -1 }.

filter

object

Optionales Filterobjekt. In der Praxis verwendet die Benutzeroberfläche dies für die Freitextsuche und aufzeichnungsspezifische Teilmengen.

Alle Dateien abrufen

Antwort

array of file objects

array

Das Backend gibt ein einfaches Array von Dateieinträgen zurück, kein Objekt-Wrapper.

Antwort: Alle Dateien abrufen

JSON

[
  {
    "_id": "680100000000000000000001",
    "id": "680100000000000000000001",
    "file_name": "Main stage mezzanine",
    "file_unique_id": "file_01abc",
    "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
    "file_path": "uploaded/f-01abc-main-stage.mp4",
    "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
    "storage_id": null,
    "file_visibility": "private",
    "module_name": "MODULE_FILES",
    "entity_name": "",
    "entity_id": null,
    "output_format": "mp4",
    "transcoding": {
      "video_transcoding": "Disabled",
      "audio_transcoding": "Disabled",
      "output_audio_bitrate": 128,
      "sample_rate": 44100
    },
    "overlay": {
      "type": "DISABLED"
    },
    "duration_ms": 612000,
    "size_bytes": 832640000,
    "created": "2026-03-24T18:55:00.000Z"
  }
]

POST

/api/files/getById

API-Token erforderlich

Rufen Sie mit dieser Methode einen einzelnen gespeicherten Dateieintrag ab. Sie liefert vollständige Metadaten und den Verarbeitungsstatus für Formulare, Auswahldialoge und nachgelagerte Workflows.

Parameter im Request-Body

string

Kennung des Dateieintrags, den Sie abrufen möchten.

Datei nach ID abrufen

Antwort

file object

object

Der gespeicherte Dateieintrag einschließlich aktueller Metadaten, Medienmetriken und Verarbeitungseinstellungen.

Antwort: Datei nach ID abrufen

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/update

API-Token erforderlich

Aktualisieren Sie mit dieser Methode eine bereits verwaltete Datei. Reine Metadatenänderungen sind leichtgewichtig; Änderungen an Format oder Transcodierung können zusätzlich eine Neuverarbeitung der gespeicherten Datei auslösen.

Parameter im Request-Body

string

Kennung des zu aktualisierenden Dateieintrags.

file payload fields

mixed

Der Request-Body entspricht create und kann bei Format- oder Transcodierungsänderungen auch eine Hintergrundkonvertierung auslösen.

Datei aktualisieren

curl --request POST \
  --url http://localhost/api/files/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "Main stage mezzanine updated",
  "file_visibility": "private",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "output_format": "mp4",
  "file_unique_id": "file_01abc",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "id": "680100000000000000000001"
}'

Antwort

updated file object

object

Das Backend gibt den aktualisierten Dateieintrag zurück, nach Abschluss des Speichervorgangs.

Antwort: Datei aktualisieren

JSON

{
  "_id": "680100000000000000000001",
  "id": "680100000000000000000001",
  "file_name": "Main stage mezzanine updated",
  "file_unique_id": "file_01abc",
  "file_description": "Uploaded mezzanine asset for overlay and playback workflows.",
  "file_path": "uploaded/f-01abc-main-stage.mp4",
  "storage_type": "STORAGE_TYPE_INTERNAL_DISK",
  "storage_id": null,
  "file_visibility": "private",
  "module_name": "MODULE_FILES",
  "entity_name": "",
  "entity_id": null,
  "output_format": "mp4",
  "transcoding": {
    "video_transcoding": "Disabled",
    "audio_transcoding": "Disabled",
    "output_audio_bitrate": 128,
    "sample_rate": 44100
  },
  "overlay": {
    "type": "DISABLED"
  },
  "duration_ms": 612000,
  "size_bytes": 832640000,
  "created": "2026-03-24T18:55:00.000Z"
}

POST

/api/files/remove

API-Token erforderlich

POST

/api/files/removeByPath

API-Token erforderlich

POST

/api/files/copyTo

API-Token erforderlich

POST

/api/files/getCopyProgressById

API-Token erforderlich

POST

/api/files/getStat

API-Token erforderlich

Diese Methode zeigt den aktuellen Fortschritt einer Dateikonvertierung oder Neuverarbeitung. Nutzen Sie sie nach dem Erstellen oder Aktualisieren einer Datei, um zu erkennen, ob die Ausgabe noch verarbeitet wird, nahezu fertig ist oder nicht weiterläuft.

Besonders hilfreich sind dabei Bitrate, FPS, Ausgabedauer, Verarbeitungsgeschwindigkeit und Fortschrittsstatus.

Parameter im Request-Body

Diese Methode hat keine Parameter

Dateiverarbeitungsstatus abrufen

Antwort

processData[]

array

Aktuelle Statistiken des Hintergrund-Transcoding-Workers, die der Dateimanager regelmäßig abruft.

processData[].bitrate / bitrate_kbits

mixed

Aktuelle von FFmpeg gemeldete Bitrate für den aktiven Umschreibprozess.

processData[].fps / out_time_ms / speed / progress

mixed

Für Operatoren aufbereitete Fortschrittswerte, die das Dashboard während der Dateikonvertierung anzeigt.

Antwort: Dateiverarbeitungsstatus abrufen

JSON

Zurück zuAufzeichnungen Weiter zuWebplayer