Skip to content

Commit 3b7425e

Browse files
JulieWinchesterJulieWinchester
committed
Add Use Case 7: Scene with Audio
1 parent 5bdc683 commit 3b7425e

File tree

1 file changed

+148
-121
lines changed

1 file changed

+148
-121
lines changed

‎source/presentation/4.0/index.md‎

Lines changed: 148 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1465,137 +1465,164 @@ A Scene or a Canvas may be treated as a content resource, referenced or describe
14651465
14661466
-->
14671467

1468-
## Use Case 7: Another Complex Scene
1468+
## Use Case 7: Scene with Audio
14691469

1470-
What is it
1470+
This example is a Manifest with a single Scene with a duration. Multiple Audio Emitter Annotations are painted into the Scene, with positional emitters used to create a 3D audio experience. Some of the Audio Emitter Annotations are only painted into the Scene for a limited period of time, producing dynamic change in the sounds heard within the Scene. A commenting Annotation is also provided to highlight the instant in time when a change in sound occurs.
14711471

1472-
### More on Point and Fragment Selectors
1472+
A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection). When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region. Both patterns are used in this example.
14731473

1474-
A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection).
1474+
An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. In this example this is used for a comment Annotation.
14751475

1476-
```json
1477-
{
1478-
"id": "https://example.org/iiif/3d/anno1",
1479-
"type": "Annotation",
1480-
"motivation": ["painting"],
1481-
"body": {
1482-
"id": "https://example.org/iiif/assets/model1.glb",
1483-
"type": "Model"
1484-
},
1485-
"target": {
1486-
"id": "https://example.org/iiif/selectors/model1-glb-sr",
1487-
"type": "SpecificResource",
1488-
"source": [
1489-
{
1490-
"id": "https://example.org/iiif/scene1",
1491-
"type": "Scene"
1492-
}
1493-
],
1494-
"selector": [
1495-
{
1496-
"id": "https://example.org/uuid/9fbd580b-895b-41b9-974a-1553329037f2",
1497-
"type": "PointSelector",
1498-
"x": -1.0,
1499-
"y": -1.0,
1500-
"z": 3.0,
1501-
"refinedBy": {
1502-
"id": "https://example.org/uuid/3d0d097b-2b37-4a15-b6a5-506e417d5115",
1503-
"type": "FragmentSelector",
1504-
"value": "t=45,95"
1505-
}
1506-
}
1507-
]
1508-
}
1509-
}
1510-
```
1511-
1512-
When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region:
1476+
In this example, the audio content resources have durations that do not match the Scene's duration. The Annotation property [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) is used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation.
15131477

1514-
```json
1515-
{
1516-
"id": "https://example.org/iiif/3d/anno1",
1517-
"type": "Annotation",
1518-
"motivation": ["painting"],
1519-
"body": {
1520-
"id": "https://example.org/iiif/assets/model1.glb",
1521-
"type": "Model"
1522-
},
1523-
"target": "https://example.org/iiif/scene1#xyz=-1,-1,3&t=45,95"
1524-
}
1525-
```
1526-
1527-
An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration.
1528-
1529-
```json
1478+
```jsonc
15301479
{
1531-
"id": "https://example.org/iiif/3d/anno1",
1532-
"type": "Annotation",
1533-
"motivation": ["painting"],
1534-
"body": {
1535-
"id": "https://example.org/iiif/assets/model1.glb",
1536-
"type": "Model"
1537-
},
1538-
"target": {
1539-
"type": "SpecificResource",
1540-
"source": [
1541-
{
1542-
"id": "https://example.org/iiif/scene1",
1543-
"type": "Scene"
1544-
}
1545-
],
1546-
"selector": [
1547-
{
1548-
"type": "PointSelector",
1549-
"x": -1.0,
1550-
"y": -1.0,
1551-
"z": 3.0,
1552-
"instant": 45.0
1480+
"@context": "http://iiif.io/api/presentation/4/context.json",
1481+
"id": "https://example.org/iiif/3d/model_origin.json",
1482+
"type": "Manifest",
1483+
"label": { "en": ["Use Case 7: Scene with Audio"] },
1484+
"items": [
1485+
{
1486+
"id": "https://example.org/iiif/scene1/page/p1/1",
1487+
"type": "Scene",
1488+
"label": { "en": ["Positional Audio Symphony Hall Experience"] },
1489+
"duration": 60,
1490+
"items": [
1491+
{
1492+
"id": "https://example.org/iiif/3d/anno1",
1493+
"type": "Annotation",
1494+
"motivation": ["painting"],
1495+
"body": {
1496+
"id": "https://example.org/iiif/audio/1",
1497+
"type": "AmbientAudio",
1498+
"source": {
1499+
"id": "https://example.org/iiif/assets/symphony_hall_ambience.mp3",
1500+
"type": "Audio",
1501+
"format": "audio/mp3"
1502+
},
1503+
"volume": {
1504+
"id": "https://example.org/iiif/value/1",
1505+
"type": "UnitValue",
1506+
"unit": "relative",
1507+
"quantity": 0.1
15531508
}
1554-
]
1509+
},
1510+
"target": "https://example.org/iiif/scene1"
1511+
},
1512+
{
1513+
"id": "https://example.org/iiif/3d/anno2",
1514+
"type": "Annotation",
1515+
"motivation": ["painting"],
1516+
"timeMode": "trim",
1517+
"body": {
1518+
"id": "https://example.org/iiif/audio/2",
1519+
"type": "PointAudio",
1520+
"source": {
1521+
"id": "https://example.org/iiif/assets/orchestra_percussion_120s.mp3",
1522+
"type": "Audio",
1523+
"format": "audio/mp3"
1524+
},
1525+
"volume": {
1526+
"id": "https://example.org/iiif/value/2",
1527+
"type": "UnitValue",
1528+
"unit": "relative",
1529+
"quantity": 0.2
1530+
}
1531+
},
1532+
"target": {
1533+
"id": "https://example.org/iiif/selectors/anno2",
1534+
"type": "SpecificResource",
1535+
"source": [
1536+
{
1537+
"id": "https://example.org/iiif/scene1",
1538+
"type": "Scene"
1539+
}
1540+
],
1541+
"selector": [
1542+
{
1543+
"id": "https://example.org/uuid/9fbd580b-895b-41b9-974a-1553329037f2",
1544+
"type": "PointSelector",
1545+
"x": -3.0,
1546+
"y": 0.0,
1547+
"z": -2.0,
1548+
"refinedBy": {
1549+
"id": "https://example.org/uuid/3d0d097b-2b37-4a15-b6a5-506e417d5115",
1550+
"type": "FragmentSelector",
1551+
"value": "t=0,30"
1552+
}
1553+
}
1554+
]
1555+
}
1556+
},
1557+
{
1558+
"id": "https://example.org/iiif/3d/anno3",
1559+
"type": "Annotation",
1560+
"motivation": ["painting"],
1561+
"timeMode": "loop",
1562+
"body": {
1563+
"id": "https://example.org/iiif/audio/3",
1564+
"type": "SpotAudio",
1565+
"source": {
1566+
"id": "https://example.org/iiif/assets/orchestra_tuba_10s.mp3",
1567+
"type": "Audio",
1568+
"format": "audio/mp3"
1569+
},
1570+
"angle": 45.0,
1571+
"volume": {
1572+
"id": "https://example.org/iiif/value/3",
1573+
"type": "UnitValue",
1574+
"unit": "relative",
1575+
"quantity": 0.3
1576+
},
1577+
"lookAt": "https://example.org/iiif/scene1"
1578+
},
1579+
"target": "https://example.org/iiif/scene1#xyz=3,0,-2&t=30,60"
1580+
}
1581+
],
1582+
"annotations": [
1583+
{
1584+
"id": "https://example.org/iiif/3d/commenting",
1585+
"type": "Annotation",
1586+
"motivation": ["commenting"],
1587+
"bodyValue": "This is the point when the percussion stops playing and the tuba begins playing.",
1588+
"target": {
1589+
"type": "SpecificResource",
1590+
"source": [
1591+
{
1592+
"id": "https://example.org/iiif/scene1",
1593+
"type": "Scene"
1594+
}
1595+
],
1596+
"selector": [
1597+
{
1598+
"type": "PointSelector",
1599+
"instant": 30.0
1600+
}
1601+
]
1602+
}
1603+
},
1604+
],
15551605
}
1606+
]
15561607
}
15571608
```
15581609

1559-
### Time mode
1560-
1561-
The Annotation's [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) can be used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation.
1562-
1563-
It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`.
1564-
1565-
1566-
An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration.
1567-
1568-
1569-
### Audio and 3D
1570-
1571-
1572-
AmbientAudio (everywhere)
1573-
PointAudio (sphere)
1574-
SpotAudio (cone)
1575-
1576-
source: Audio (id, type, format, profile, duration, label)
1577-
volume: UnitValue (value: 0.3, unit: relative)
1578-
angle: degrees of the cone, per SpotLight
1579-
1580-
Ambient and Point can be painted on to Canvas
1581-
hidden on audio = inaudible
1582-
1583-
1584-
All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces.
1585-
1586-
"Exclude Audio"
1587-
1588-
1589-
1590-
1591-
1592-
1593-
1594-
1595-
1596-
1597-
1610+
>
1611+
**Key Points**
1612+
* The Scene has a duration of 60 seconds.
1613+
* The Scene has three different Audio Emitter Annotations painted into the Scene---AmbientAudio, PointAudio, and SpotAudio. Each Audio Emitter uses the `volume` property to specify audio volume.
1614+
* AmbientAudio targets the Scene via a reference to the Scene URI, which implicitly targets the Scene's entire duration.
1615+
* PointAudio targets the Scene with a PointSelector to paint the Audio Emitter at a specific point in 3D space, and that PointSelector is temporally scoped by a FragmentSelector to target the first 30 seconds of the Scene duration.
1616+
* SpotAudio targets the Scene via a URL fragment to demonstrate an alternate approach to target a point and range of time in the Scene. It uses the `lookAt` property to point the Audio Emitter cone toward the Scene origin.
1617+
* The content resources for PointAudio and SpotAudio use the property `timeMode` to specify different ways of handling mismatches between content resource audio length and Scene duration.
1618+
* A commenting Annotation targets the Scene at the instant corresponding to 30 seconds of the Scene duration to highlight the point at which PointAudio stops playing and SpotAudio begins playing.
1619+
* It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`.
1620+
{: .note}
15981621

1622+
__Definitions__<br/>
1623+
Classes: [Manifest](#model/Manifest), [Scene](#model/Scene), [SpecificResource](#model/SpecificResource), [PointSelector](#model/PointSelector), [FragmentSelector](#model/FragmentSelector), [AmbientAudio](#model/AmbientAudio), [PointAudio](#model/PointAudio), [SpotAudio](#model/SpotAudio)<br/><br/>
1624+
Properties: [duration](#model/duration), [volume](#model/volume), [angle](#model/angle), [lookAt](#model/lookAt), [timeMode](#model/timeMode)
1625+
{: .note}
15991626

16001627

16011628
# Nesting (more about Containers as Content Resources)
@@ -1684,7 +1711,7 @@ Manifest
16841711

16851712
## Annotation Page
16861713

1687-
Annotation Pages are used to group Annotations. In cases where many annotations are present, such as when transcription, translation, and commentary are associated with a manuscript, it can be useful to separate these annotations into groups that can facilitate improved user interactions in a client.
1714+
Annotation Pages are used to group Annotations. In cases where many annotations are present, such as when transcription, translation, and commentary are associated with a manuscript, it can be useful to separate these annotations into groups that can facilitate improved user interactions in a client.
16881715

16891716
Each Annotation Page can be embedded or externally referenced. Clients should process the Annotation Pages and their items in the order given in the Container. Publishers may choose to expedite the processing of embedded Annotation Pages by ordering them before external pages, which will need to be dereferenced by the client. Order can be significant, however. Annotations are assigned an ascending [z-index](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index) from the first annotation encountered. Annotations with a higher z-index will render in front of those with a lower z-index when displayed on a Canvas.
16901717

@@ -1814,7 +1841,7 @@ It is important to be able to position the textual body of an annotation within
18141841

18151842
An Annotation with the motivation `linking` is used to create links between resources, both within the Manifest or to external content on the web, including other IIIF resources. Examples include linking to the continuation of an article in a digitized newspaper in a different Canvas, or to an external web page that describes the diagram in the Canvas. A client typically renders the links as clickable "Hotspots" - but can offer whatever accessible affordance as appropriate. The user experience of whether the linked resource is opened in a new tab, new window or by replacing the current view is up to the implementation.
18161843

1817-
The resource the user should be taken to is the `body` of the annotation, and the region of the Container that the user clicks or otherwise activates to follow the link is the `target`:
1844+
The resource the user should be taken to is the `body` of the annotation, and the region of the Container that the user clicks or otherwise activates to follow the link is the `target`:
18181845

18191846
```jsonc
18201847
{

0 commit comments

Comments
 (0)