When audio or video plays nothing in a IIIF viewer, the fault is almost always a time-based canvas missing its duration, or a painting annotation that does not properly target the canvas with a temporal fragment. AV in IIIF Presentation API 3 works exactly like images, except canvases gain a time dimension — so the errors cluster around that one extra property.

Why does my AV canvas play nothing at all?

A time-based canvas must declare duration in seconds, and the painting annotation must target that canvas. The minimal correct shape for an audio recording:

{
  "type": "Canvas",
  "id": "https://example.org/iiif/rec-9/canvas/1",
  "duration": 1985.0,
  "items": [{
    "type": "AnnotationPage",
    "items": [{
      "type": "Annotation",
      "motivation": "painting",
      "body": {
        "type": "Sound",
        "id": "https://media.example.org/rec-9.mp4",
        "format": "audio/mp4",
        "duration": 1985.0
      },
      "target": "https://example.org/iiif/rec-9/canvas/1"
    }]
  }]
}

Drop duration from the canvas and most viewers render an empty stage. That single omission accounts for the majority of "nothing happens" reports.

Does an AV canvas need width and height?

It depends on the medium:

Canvas type	Required dimensions
Audio only	duration
Video	width, height, duration
Image + audio	width, height, duration

Putting width/height on an audio-only canvas is harmless but pointless; omitting duration on any time-based canvas breaks it. Diagnose by fetching the manifest and checking the canvas has a numeric duration.

Which formats actually play?

IIIF does not transcode — the browser does the decoding, so format support is a browser question. The safe baseline is MP4 with H.264 video and AAC audio. WebM plays in Chrome and Firefox but not reliably in Safari. If your video fails only in some browsers, suspect the codec, not the manifest:

# Inspect what you actually have
ffprobe -hide_banner rec-9.mp4
# Re-encode to the safe cross-browser baseline
ffmpeg -i source.mov -c:v libx264 -profile:v high -c:a aac -movflags +faststart rec-9.mp4

The +faststart flag moves the index to the front so playback can begin before the whole file downloads — without it, large videos appear to "hang".

How do I add captions and they actually show?

Captions are a supplementing annotation carrying a WebVTT file, not a painting annotation:

{
  "type": "Annotation",
  "motivation": "supplementing",
  "body": {
    "type": "Text",
    "id": "https://media.example.org/rec-9.vtt",
    "format": "text/vtt",
    "label": { "en": ["Captions (English)"] }
  },
  "target": "https://example.org/iiif/rec-9/canvas/1"
}

Place it in the canvas's annotations array (not items). Avplayer and the Universal Viewer pick up text/vtt automatically. If captions do not appear, you almost certainly put them under items (painting) instead of annotations (supplementing).

Why is only part of my recording playing?

Two suspects. Either the canvas duration is shorter than the media, or the painting annotation targets a temporal slice with a media fragment such as #t=0,300 — which deliberately plays only the first five minutes. Inspect the target:

.../canvas/1#t=0,300     # plays only 0–300 seconds, on purpose
.../canvas/1             # plays the whole duration

If a clip is intended, this is correct; if not, remove the #t= fragment and set duration to the full length.

A fast diagnostic order

1. Fetch the manifest; confirm every AV canvas has duration.
2. For video, confirm width and height are present too.
3. Open the media URL directly — does the browser play it? If not, it is a codec/CORS issue, not IIIF.
4. Re-encode to MP4 H.264/AAC with +faststart if any browser fails.
5. Check captions are supplementing annotations under annotations, format text/vtt.
6. Inspect target for an unintended #t= fragment truncating playback.

Key Takeaways

• Every time-based canvas needs duration; its absence is the top cause of silent failure.
• Video canvases also need width and height; audio canvases do not.
• Format support is the browser's job — ship MP4 (H.264/AAC) with +faststart.
• Captions are supplementing annotations (WebVTT, text/vtt) in the annotations array.
• Partial playback usually means a short canvas duration or a #t=start,end target fragment.
• A canvas can carry both audio and an image as separate painting annotations.

Frequently Asked Questions

Why does my IIIF audio or video canvas play nothing?

Usually the canvas lacks a duration, or the painting annotation has no temporal target. A time-based canvas must declare duration and the annotation should target the canvas with a #t= fragment for the media to attach.

Does a IIIF AV canvas need width and height?

Audio-only canvases need only duration. Video canvases need width, height and duration. Omitting duration on any time-based canvas is the most common reason a viewer shows nothing.

Which video formats do IIIF viewers support?

It depends on the browser, not IIIF. MP4 (H.264/AAC) is the safest cross-browser choice; WebM works in many but not all. Provide MP4 as the primary body to avoid codec failures.

How do I add captions or subtitles to IIIF video?

Attach a WebVTT file as a supplementing annotation on the canvas with motivation supplementing and format text/vtt. Avplayer and Universal Viewer then render the captions track.

Why is only part of my recording playing?

Your painting annotation targets a time range with #t=start,end that is shorter than the media, or the canvas duration is set too low. Check both the canvas duration and any temporal fragment on the annotation.

Can one canvas hold both audio and an image?

Yes. A canvas can carry multiple painting annotations, for example an audio body plus a still image body, each targeting the canvas. This is common for presenting a recording with a photograph of the performer or score.

Related reading

• Use the IIIF Presentation API: A Practical Guide
• Best Practices to Build IIIF manifests
• When to Annotate images with IIIF
• Beginner's Guide to IIIF CORS errors
• Troubleshooting: Set up the Mirador viewer