{
  "dataset": "ShotMetrics",
  "subtitle": "A Shot-Level Film Metrics Database",
  "description": "Field schema for the Kurosawa 30-film shot-level CSV collection used by the static ShotMetrics prototype.",
  "notes": [
    "ASL and Filtered_ASL are film-level repeated fields. Do not aggregate them by shot rows without first deduplicating by film.",
    "Stratum is currently always 0 in the audited CSV files and is not recommended as a primary chart variable.",
    "Remarks is a sparse quality flag field. It can be used to filter Low Confidence / Check records.",
    "QC Flags is the website label for the count of records with non-empty Remarks. It is a quality-control count, not a film-form metric.",
    "Plot Studio exposes a reduced metric set: ASL or Shot_Duration, CIELAB_Brightness, CIELAB_Warmth, HSV_Saturation, and Character_Shot_Scale."
  ],
  "fields": {
    "Video": {
      "type": "string",
      "level": "film",
      "meaning": "Source video filename recorded in the CSV.",
      "recommended_use": "Grouping, display, and linking each shot row back to its film source."
    },
    "ASL": {
      "type": "number",
      "level": "film",
      "meaning": "Average Shot Length for the film.",
      "recommended_use": "Film-level comparison after deduplicating by film. Do not treat as a per-shot metric."
    },
    "Filtered_ASL": {
      "type": "number",
      "level": "film",
      "meaning": "Filtered Average Shot Length for the film.",
      "recommended_use": "Film-level comparison after deduplicating by film. Do not treat as a per-shot metric."
    },
    "Stratum": {
      "type": "number",
      "level": "shot",
      "meaning": "Stratum marker generated by the workflow.",
      "recommended_use": "Currently all values are 0, so this field is not recommended as a main chart variable."
    },
    "Shot_Start": {
      "type": "number",
      "unit": "seconds",
      "level": "shot",
      "meaning": "Start time of the shot.",
      "recommended_use": "Default X axis for shot-level timelines."
    },
    "Shot_End": {
      "type": "number",
      "unit": "seconds",
      "level": "shot",
      "meaning": "End time of the shot.",
      "recommended_use": "Auxiliary timing field, useful with Shot_Start and Shot_Duration."
    },
    "Shot_Duration": {
      "type": "number",
      "unit": "seconds",
      "level": "shot",
      "meaning": "Duration of a single shot.",
      "recommended_use": "Core rhythm metric for timelines, histograms, and film-to-film comparison."
    },
    "Log_Duration": {
      "type": "number",
      "level": "shot",
      "meaning": "Log-transformed shot duration.",
      "recommended_use": "Useful for charting long-tailed shot-duration distributions."
    },
    "Is_Long_Take": {
      "type": "number",
      "level": "shot",
      "meaning": "Binary marker for long-take shots.",
      "recommended_use": "Filtering, proportions, and timeline markers."
    },
    "CIELAB_Brightness": {
      "type": "number",
      "level": "shot",
      "meaning": "Shot-level brightness feature in CIELAB-derived space.",
      "recommended_use": "Brightness timelines and distribution charts."
    },
    "CIELAB_Warmth": {
      "type": "number",
      "level": "shot",
      "meaning": "Shot-level warm/cool color feature in CIELAB-derived space.",
      "recommended_use": "Warmth timelines, distributions, and color-style exploration."
    },
    "HSV_Saturation": {
      "type": "number",
      "level": "shot",
      "meaning": "Shot-level saturation feature in HSV-derived space.",
      "recommended_use": "Saturation timelines and distribution charts."
    },
    "Face_Count": {
      "type": "number",
      "level": "shot",
      "meaning": "Detected face count for the shot.",
      "recommended_use": "Facial presence timelines, distribution charts, and film-level summaries."
    },
    "Face_Ratio_Median": {
      "type": "number",
      "level": "shot",
      "meaning": "Median face-size ratio proxy for the shot.",
      "recommended_use": "Shot-scale and facial prominence analysis."
    },
    "Face_Ratio_Max": {
      "type": "number",
      "level": "shot",
      "meaning": "Maximum face-size ratio proxy for the shot.",
      "recommended_use": "Finding shots with large facial presence or close-up-like composition."
    },
    "Face_Coverage": {
      "type": "number",
      "level": "shot",
      "meaning": "Proportion-like facial coverage feature for the shot.",
      "recommended_use": "Facial presence timelines and distribution charts."
    },
    "Character_Shot_Scale": {
      "type": "string",
      "level": "shot",
      "meaning": "Categorical proxy for character shot scale.",
      "recommended_use": "Categorical summaries such as counts, proportions, and stacked bars."
    },
    "Remarks": {
      "type": "string",
      "level": "shot",
      "meaning": "Sparse quality or review note. The audited files currently use Low Confidence / Check.",
      "recommended_use": "Filtering or flagging records that may need manual review. In the website interface, the film-level count of non-empty Remarks is labeled QC Flags."
    }
  }
}