Version 0.9
August 2024
About this Document
Introduction
Why is OSLO Needed?
Who is this for?
An Example File
Required Top-level Elements
Optional Top-level Elements
Required Waypoint-level Elements
Optional Waypoint-level Elements
Categories List
License
About this Document
This document specifies requirements and best practices for location-based media using the OSLO standard. It defines required and optional file elements, and it lays the groundwork for future enhancements by being as open and as simple as possible. While the original format has been created by Spooler, comment and feedback are encouraged.
Introduction
OSLO (Open Standard for LOcation media) is a JSON-based publishing format that enables media playback based on physical location. OSLO simplifies the creation, distribution, and consumption of place-based media experiences with a single, simple format. OSLO is a free and open standard that anyone can use to publish geo-targeted content.
Why is OSLO Needed?
To date, we’re aware of no standard publishing format for location-based media experiences. Location-based content is a wonderful medium that deserves more attention than it currently gets. GPS-enabled devices have made everyone a potential consumer of this type of content, yet many people have no idea it even exists, much less how to find it. This mirrors the state of spoken-word audio before the advent of podcasting.
We believe location media needs its “podcasting moment,” a lowering of the existing barriers to entry that will spur many more creators and innovators to jump into the space. That in turn will bring much-needed attention to the medium, benefitting both the newcomers and those already creating great content. The process begins with an open and flexible publishing standard.
Who is this for?
We believe that anyone involved in the creation, distribution, and consumption of place-based media can take advantage of OSLO’s open format to find a larger audience for this type of content experience.
Creators can use simple tools to quickly create location-based media experiences like tours, scavenger hunts, games, and more. Because the format is open and flexible, all kinds of new experiences are possible to easily create.
Developers can build tools for the creation, distribution and consumption of location-based media, knowing that a standard format will simplify their process.
Consumers will be able to discover and experience location-based content more easily. Under a single format, directories of available content could be built, which would greatly help users discover more content to enjoy.
An Example File
OSLO is designed to be simple and flexible, with as few required elements as possible. Where possible, it leverages existing open standards, like GeoJSON for location.
{
"data": {
"schema": "https://spooler.fm/oslo/schema/0.9.0",
"uuid": "acaf7b7f-e3c2-4b26-889e-4565dbd03d4e",
"pubdate": "2023-03-18T12:55:39Z",
"author": {
"name": "The Architecture Explorers",
"url": "https://www.example.com",
"email": "[email protected]"
},
"language": "en-US",
"title": "LA's Dream Architecture",
"description": "A tour of LA architecture hotspots.",
"image_url": "https://www.example.com/topimage.jpg",
"waypoints": [
{
"uuid": "81cab5fa-cd79-4da0-a718-8c48832b828b",
"title": "Hobbit Houses",
"description": "Fantastical houses and apartments in Culver City",
"pubdate": "2023-03-18T12:55:39Z",
"primary_category": "Architecture > Modern Architecture",
"image_url": "https://www.example.com/waypoint_image.jpg",
"trigger": {
"proximity": 100
},
"location": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
34.022431039,
-118.3991591769
]
},
"properties": {
"address": "3822, Dunn Drive, Los Angeles, 90232, United States"
}
}
]
},
"assets": [
{
"uuid": "68f0eb34-411b-4cf0-9b45-b5424163279f",
"label": "north",
"track_url": "https://www.example.com/hobbits_north.mp3",
"duration": 64.824,
"mime_type": "audio/mpeg"
},
{
"uuid": "157321c9-5b5c-4f34-8f1a-3338d54c5339",
"label": "south",
"track_url": "https://www.example.com/hobbits_south.mp3",
"duration": 64.824,
"mime_type": "audio/mpeg"
}
]
}
]
}
}
Required Top-level Elements
schema
Specifies the version of the OSLO file format, and links to the published current standard. This should appear at the top, if possible.
uuid
A universally unique identifier for the file itself, ensuring each file is distinct. Defined in RFC 4122.
pubdate
Publication date and time of the file, in ISO 8601 format. If the file is updated, pubdate should be set to the time of the most recent update.
author
Authorship information for the file. name is required. url, email, or other elements may be used for further clarification. Optionally, author may be used at the waypoint level to further specify ownership.
title
The title of the media experience or collection.
description
A brief description of what the file contains or represents.
Optional Top-Level Elements
language
The primary language of the file’s media, using a language-region format (e.g., “en-US” for English, United States). Described in RFC 5646. Optionally, language may also be used at the waypoint level for collections of waypoints in different languages.
image_url
A URL pointing to an image representative of the file as a whole. Square JPEG or PNG files at least 1400 X 1400 pixels should be preferred.
file_type
Creators may wish to specify whether the waypoints should be experienced in order (as in a stop-by-stop tour). If so, specify "file_type": "ordered". If the file type is ordered, each waypoint must employ the position element, described below, to indicate order of playback. If the file is simply a collection of individual waypoints, then the type can be set to “unordered.” If the file_type element is not used, the waypoints are assumed to be unordered.
copyright
An array which articulates the ownership and usage rights associated with the content. The “copyright” element lists the owner. Further elements may be added to the array to describe specific permissions. For example, "ai_access": "denied" could be an element added to specify the level of access AI services are allowed. The absence of the copyright element in a file does not mean that the file is in the public domain.
Required Waypoint-level Elements
waypoints is an array, and is required. The waypoints array contains the set of location and media elements that comprise the majority of the experience. Each waypoint contains one location and one or more media assets.
uuid
A universally unique identifier for the waypoint, ensuring each waypoint is distinct. Defined by the IETF in RFC 4122.
title
The name or title of the waypoint.
description
A brief description of the waypoint.
pubdate
Publication date and time of the waypoint, in ISO 8601 format. If the file is updated, pubdate should be set to time of most recent update.
primary_category
One category is required for each waypoint. Optionally, two more categories may be declared; use secondary_category and tertiary_category elements to describe those. Further category information is located in the Categories List section below.
location
Contains geographical data for the waypoint. Because of its flexibility and widespread adoption, OSLO uses GeoJSON objects for the location element. In the example file, a point with specific lat/long coordinates is provided. However, GeoJSON allows for great flexibility with regard to the geographic object referenced. Location may be defined as an area, or an indoor space, or even a different planetary body. Refer to the GeoJSON format specification (RFC 7946) for representing geographical features.
Within location, the optional properties object contains additional information about the feature—in this case, the location’s address.
assets
An array of objects, each representing a media file associated with the waypoint. A waypoint may contain one or more media files.
If only one file is present, that file should be played according to the trigger parameter. However, when designing an experience for location-based playback, it may be preferable to play a different media file based on different conditions. For example, a creator may wish to provide a different file based on time of year, or time of day, the direction the user is traveling, or the speed at which they are moving. In that case, multiple audio files may be provided.
If multiple files are provided, the label element is required, to indicate which file should be played. In the example file, if the application determines the user is traveling north, the first file would be played. If south, the second file would be played. Application developers who include multiple audio elements should take care to ensure one audio file is set to play by default if no further information is available.
track_url
A URL to the actual media file.
mime_type
The MIME type of the media file, indicating the file format. OSLO does not specify which types of media files (eg., audio vs. video) are acceptable.
duration
The duration of the media file in seconds.
Optional Waypoint-Level Elements
trigger
An object containing information regarding when the waypoint’s media should be played with regard to the location. In this case, the application uses "proximity": 100 to indicate how far away from the location point the media file should start playing, but the object is free-form and anything can be used as a trigger, including other json objects.
Applications with access to a mapping service with route data could use ETA to determine when to trigger media playback. For example, media could be triggered to play when the user’s ETA equals the duration of the file.
position
An integer that specifies the waypoint’s order relative to other waypoints in the file. If the file_type element is present and set to “ordered,” this element is required. No two waypoints should have the same position number to avoid ambiguity in ordering.
image_url
A URL pointing to an image representative of the waypoint. Square JPEG or PNG files at least 1400 X 1400 pixels are preferred.
bitrate
The bitrate of the audio file in kilobits per second (kbps).
sample_rate
The sample rate of the audio file in Hertz (Hz).
size
The file size of the audio clip in bytes.
Subject Categories
The waypoint-level category elements (the required primary_category, as well as the optional secondary_category and tertiary_category) may use this list of categories and subcategories. Up to three categories or subcategories may be listed.
- Architecture
- Historic Architecture
- Modern Architecture
- Arts and Culture
- Outdoor Art
- Visual Art
- Performing Arts
- Cultural Landmark
- Museums
- Film and TV
- LGBTQ+
- Discovery
- Fiction
- History
- Politics
- Crime
- War
- First Nations
- Religious History
- Kids and Family
- Kids’ Stories
- Education
- Kids’ Activities
- Kids’ Games
- Nature
- Outdoor Activities
- Geology
- Flora and Fauna
- Parks
- Hospitality
- Lodging
- Shopping
- Food and Drink
- Utility
- Sports and Adventure
- General
License
OSLO is offered by Spooler Media under the terms of the Attribution-ShareAlike Creative Commons license.