Movie attribution and research metadata

This document describes how attribution and research-use permissions are captured for student-uploaded movies, stored, and reflected in object storage for traceability.

Philosophy

Students retain control over how their uploaded videos may be used in academic research and whether they receive credit by name. The system records these choices at upload time so that:

The S3 bucket outlives the stack (it is the long-term archive of student videos; see S3 and Plant Tracer). Therefore metadata must live in the MP4 file so that the object remains self-describing even if the DynamoDB database is gone.

  • Researchers can determine which videos may be used in studies and under what attribution (by name or anonymous).

  • Choices are stored in the application database (DynamoDB), as S3 object metadata (x-amz-meta-), and **in the MP4 file* (comment atom), so that the same terms travel with the data and remain valid even if the database is removed or migrated.

  • The presigned S3 upload includes these metadata fields in the signature, so the client cannot change attribution or research-use after the server has issued the upload; the object stored in S3 matches what was consented to.

The two main choices are:

  1. Research use — Whether the uploaded movie may be used in academic research.

  2. Credit by name — If research use is allowed, whether the student wants to be credited by name. If yes, a “Name for attribution” value is stored. If no, the video may still be used in research but anonymously.

Three-state model

Each of research_use and credit_by_name is a three-state value:

  • 1 — explicitly Yes

  • 0 — explicitly No

  • None — not yet answered (the user did not select a radio button, or the record predates the radio-button UI)

The sentinel string "not-answered" is used when either field has not been answered in S3 object metadata and MP4 embedded metadata (where None cannot be stored directly). Legacy records with 0 stored before the radio-button UI was introduced are treated as an explicit No (the original checkbox was visible to the user and they chose not to check it).

Implementation

Upload form

  • Research use — Yes/No radio group. Neither option is pre-selected, leaving the value as not answered until the student makes a choice.

  • Credit by name — Yes/No radio group. Shown only when research use is Yes. Neither option is pre-selected by default.

  • Name for attribution: Text field. Shown and enabled only when both research use is Yes and credit by name is Yes.

UI logic is implemented in sync_attribution_ui() in src/app/static/planttracer.js, with the form markup in src/app/templates/upload.html.

API and database

  • Endpoint: POST /api/new-movie accepts (in addition to existing parameters) form fields: research_use ("1", "0", or omitted), credit_by_name ("1", "0", or omitted), and attribution_name (string). Omitted fields are stored as None in DynamoDB.

  • Storage: The movie record in DynamoDB (see schema.Movie and odb.create_new_movie) stores:

    • research_use: 1, 0, or None

    • credit_by_name: 1, 0, or None

    • attribution_name: string or null (only meaningful when credit_by_name == 1)

  • Validation: credit_by_name != 1 forces attribution_name to null on the server.

Presigned S3 upload and object metadata

  • Presigned post: s3_presigned.make_presigned_post() takes research_use, credit_by_name, and attribution_name (as strings). These are added to both Fields and Conditions so that the presigned POST signature binds the client to those exact values.

  • S3 object metadata: The same values are sent as S3 user metadata using the keys:

    • x-amz-meta-research-use — "1", "0", or "not-answered"

    • x-amz-meta-credit-by-name — "1", "0", or "not-answered"

    • x-amz-meta-attribution-name — name string, or empty string

    Because they are in the presigned Fields, the client must send these exact values when uploading; the object in S3 therefore carries the same research and attribution metadata as the DynamoDB record.

  • Client: upload_movie_post() in planttracer.js sends research_use and credit_by_name only when a radio button has been selected (omits the field entirely when not answered), and sends attribution_name to /api/new-movie. The API returns a presigned post whose fields already contain the signed metadata; the client posts those fields (and the file) to S3 without modifying them.

Traceability

  • DynamoDB: Each movie row has research_use, credit_by_name, and attribution_name for queries and reporting.

  • S3: Each object has the same information in x-amz-meta-*, so that exports, copies, or downstream systems can enforce or display attribution and research-use without relying solely on the application database.