Files
Files is the asset-management layer of Callaba Engine. It is where uploaded media becomes something the rest of the platform can actually reuse: an archive source, a playback asset, an overlay file, or a deliverable that should be copied somewhere durable.
In practice this module matters whenever the platform stops being only live. The file manager sits in the middle of the day-two work that teams actually do: prepare media, convert it into the right shape, reuse it in more than one workflow, and move it out to storage when it is ready.
Examples by preset
The file manager is easiest to understand when you separate three recurring production shapes: register an uploaded asset, save a converted derivative, and move a finished asset into storage.
{
"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
}
}{
"file_id": "680100000000000000000001",
"storage_type": "STORAGE_TYPE_S3",
"storage_id": "680200000000000000000001"
}Workflow examples
Upload once, reuse many times
Use the file manager when one uploaded asset should later feed overlays, playlist-style playback, or additional output modules without being uploaded again.
Convert at save time
Use the file create and update flows when the saved file should become a different deliverable such as MP3 or HLS. The team can then follow progress through getStat instead of guessing whether conversion is still moving.
Push completed assets to storage
Use copyTo and getCopyProgressById when local or generated assets should be moved into S3-style storage after capture or preparation is complete.
Create saves a managed file row in the file manager. Use it when an uploaded asset should become something the rest of the platform can work with reliably: a named file, a converted deliverable, or a reusable playback or overlay asset.
This method is more than metadata storage. If the requested output_format or transcoding settings differ from the uploaded asset, Callaba can start the conversion work that turns the source file into the deliverable the team actually needs.
Examples by preset on this method show the most useful create shapes: preserve an uploaded MP4 as-is, derive an MP3 deliverable, or materialize an HLS package.
Use this preset when an uploaded mezzanine file should become a reusable managed asset without additional conversion.
This is the cleanest file-manager path: upload first, then register the asset with metadata, visibility, and a durable file row.
Use this preset when the stored asset should be rewritten into a simpler audio deliverable during the save flow.
The file row is created first, then the background transcoding worker produces the derivative output and exposes progress through getStat.
Use this preset when the resulting asset should be materialized as an HLS package instead of a single file.
This is useful when the managed file will be handed to a playback or delivery workflow that expects an HLS-style directory output.
Dashboard label: Name.
Human-facing asset name stored in the file manager.
Dashboard label: File.
Path produced by uploadFile or already known to the platform.
Upload correlation id used to connect an in-progress upload with the saved file row.
Dashboard label: Visibility.
Controls whether the stored file should be treated as public or private in downstream UI flows.
Optional description stored on the file row.
Dashboard label: Output format.
If the requested format differs from the uploaded extension, the backend starts a background rewrite flow.
Optional transcoding settings used when the file should be converted into a different deliverable.
Optional source context for UI-driven flows. In practice the file manager most often saves rows under MODULE_FILES.
Saved file identifiers and the persisted file name.
Stored file location plus the upload correlation id.
Saved visibility and descriptive metadata for the asset.
Output-format and processing state stored with the file row.
Computed media metrics and backend-managed timestamp fields.
Use this when the first production need is simple: get the media into Callaba so the asset can be named, converted, reused, copied, or attached to later workflows.
If file_unique_id is provided, the upload path can reconnect the finished file to a file row that was already created while the upload was still in progress.
Binary file payload uploaded to the managed file area.
Optional correlation id used by the dashboard to attach the upload to a pending file row.
Stored file name generated for the uploaded asset.
Base folder used by the uploaded-file storage path.
Timestamp returned by the upload path.
Get files count is the quick inventory companion for the file-manager listing. Use it when the team needs fast pagination or capacity numbers without pulling the full asset list first.
Optional filter object used to scope the file count by module, entity, or custom search conditions.
Total number of files visible to the authenticated user for the applied filter.
Get all files returns the visible file-manager rows for the current filter. Use it when the team needs one inventory view of reusable assets, generated files, or recording outputs that should still be treated as managed media.
Optional page size for file-manager listing queries.
Optional offset for paginated file listing.
Optional sort descriptor. The dashboard defaults to { created: -1 }.
Optional filter object. In practice the UI uses this for free-text search and recording-owned subsets.
The backend returns a bare array of file rows, not a wrapped object.
Get file by id loads one saved file row. Use it when a form, picker, or downstream workflow needs the full metadata and processing state for a single asset.
Identifier of the file row you want to inspect.
The saved file row including current metadata, media metrics, and processing settings.
Update is where the team adjusts a managed asset after it already exists. Simple metadata edits stay lightweight, while format or transcoding changes can also trigger the work needed to reshape the stored file into a better deliverable.
Identifier of the file row being updated.
The update contract mirrors create and can also trigger a background rewrite when format or transcoding changes.
The backend returns the updated file row after the save path completes.
Remove deletes the managed file row and attempts to delete the backing asset from its current storage location. Use it when the team is sure the asset should disappear from both inventory and storage, not just from the current screen.
Identifier of the file row to delete.
Indicates that the file row and its backing file path were removed successfully.
Use this when a temporary upload should be discarded quickly before it becomes part of a longer-lived asset workflow.
Absolute or managed file path that should be cleared without first resolving a file id.
The path cleanup flow completes without returning a file object.
Copy to starts a managed handoff of a file into another storage target. Use it when the asset is ready to leave local working storage and become part of a longer-lived archive or delivery destination.
Once the copy is accepted, use getCopyProgressById to track completion.
Identifier of the managed file being copied.
Target storage family such as STORAGE_TYPE_INTERNAL_DISK or an external object-storage type.
Optional storage identifier when the destination is an external configured storage target.
The copy job has been accepted and progress can now be monitored by file id.
Use this when the team needs a live answer about whether a file handoff is still moving and how far it is from completion.
Identifier of the source file whose copy progress should be inspected.
Copy progress percentage derived from copied bytes versus total bytes.
Becomes true after the destination copy has fully completed.
Get file process stat exposes the live progress of a file conversion or rewrite. This is the operator-facing companion to create and update when the team needs to know whether a new deliverable is still processing, nearly done, or stalled.
In practice the most useful fields are bitrate, FPS, output time, speed, and progress state.
Current background transcoding-worker statistics exposed by the file manager polling loop.
Current FFmpeg-reported bitrate for the active rewrite process.
Operator-facing progress fields used by the dashboard while a file rewrite is running.