Create docs for MSU with guidance for ingesting MP3 files

[elynema]

Description

Documentation is needed for using MP3 files as source derivatives for the creation of new objects in an Avalon instance. Avalon generally assumes that files will be handled through its processing pipeline, but this effort is to provide support for cases in which pre-existing derivative files need to be used and served as the media assets for media objects in Avalon.

Done Looks Like

• Documentation written for creating objects with single files for progressive download aimed at MSU audience
• Documentation adapted to generic documentation applicable to Docker installs added to the Avalon wiki

Notes

Requirements

• A way to create or update objects with the API
  • Derivative file locations are supplied with the API request to create the item
• Copying derivative files into the correct location

1. Derivatives are stored in the appropriate directory for being served
2. Object is created via API request with derivative paths passed in for

Fields Supplied to New Objects

• metadata (bib import from service)
• media file paths (derivatives in Amazon S3 cloud storage, with S3 file paths)
• technical metadata (mime type, width/height etc.)
  • is this available from the vendor?
  • is it uniform across all of the derivatives and can be applied the same for each object?
  • if not, it could be filled out via an ffprobe run

Technical Metadata values

• derivativeFile: s3 path
• bitrate
• codec
• mime type
• quality (always set to "high" for single derivative items)
• file size

We should tell them to create things in the S3 bucket in the structure that Avalon expects.
They can create a bucket in S3 with this structure:
avalon-demo-derivatives/UUID/quality-high/derivative_file.mp3

Example object in Demo:
https://demo.avalonmediasystem.org/media_objects/t148fh39z

Example Request

POST https://demo.avalonmediasystem.org/media_objects.json

{
    "collection_id": "0g354f48h",
    "files": [
        {
            "workflow_name": "pass_through",
            "percent_complete": "100.0",
            "status_code": "COMPLETED",
            "structure": null,
            "label": null,
            "thumbnail_offset": 0,
            "poster_offset": 0,
            "physical_description": null,
            "file_location": "s3://avalon-demo-masterfiles/uploads/3f8982fa-78fd-497e-87b4-0b3b07c53cfe/jazz-performance.mp3",
            "file_size": 2614033,
            "duration": "187951",
            "date_digitized": "2024-07-09T19:45:43Z",
            "file_checksum": null,
            "file_format": "Sound",
            "other_identifier": [],
            "captions": null,
            "captions_type": null,
            "supplemental_file_captions": [],
            "comment": [],
            "display_aspect_ratio": null,
            "original_frame_size": null,
            "width": null,
            "height": null,
            "files": [
                {
                    "label": "quality-high",
                    "id": "4e9b88d5-839a-4035-85a1-d6dc8c02a62e",
                    "url": "5dc15c20-75c6-44dd-8bf5-03d76c3b38df/jazz-performance.mp3",
                    "hls_url": "https://streaming.demo.avalonmediasystem.org/avalon/5dc15c20-75c6-44dd-8bf5-03d76c3b38df/jazz-performance.mp3",
                    "duration": 187951,
                    "mime_type": "audio/mpeg",
                    "audio_bitrate": "111231.0",
                    "audio_codec": "mp3",
                    "video_bitrate": null,
                    "video_codec": null,
                    "width": null,
                    "height": null,
                    "location": "5dc15c20-75c6-44dd-8bf5-03d76c3b38df/jazz-performance.mp3",
                    "track_id": "1",
                    "hls_track_id": null,
                    "managed": false,
                    "derivativeFile": "s3://avalon-demo-derivatives/5dc15c20-75c6-44dd-8bf5-03d76c3b38df/jazz-performance.mp3"
                }
            ]
        }
    ],
    "fields": {
        "title": "MP3 Item",
        "date_issued": "2024"
    }
}