API
From ActiveArchives
Contents |
Plugins
There are three kinds of plugins in AA: sniffers, filters, and exporters.
The lifecycle of a resource in AA: sniff, filter, and export. In parallel, Annotations allow resources to be described, tagged, reorganized.
Sniffers
Input: URL, Output: Annotation (Structured Text) containing metadata, links
Motivation: Command line tools often offer extremely useful information about resources (ffmpeg to check a movie, exiftool to explore the metadata of a tag, an HTML parser to extract the structure of a page). Aim to capture this ability in a format (using RDF) to enable its use / mixing.
Position: Tool-specific views of media -- tries *not* to make clean abstractions (multi-purpose Image viewer), but rather content/format/tool specific (think Linux one-thing-done-really-well). A sniffer corresponds to a "source" of information about a resource. AA's ability to combine different sources of information (through in part the use of RDF) allows for this diversity of information to be merged as needed / desired. (Example: Could use a youtube tag, and an EXIF image tag together).
!? URL | sniffer => new URL which is actually the URL of the annotation!
| Name | Notes |
|---|---|
| ffmpeg | |
| exiftool | |
| youtube-api | |
| vimeo-api | |
| HTML5lib (python) | |
| RDFa | |
| identify (imagemagick) |
Filters
Input: Media URL, Output: (New) Media URL. Typically Asynchronous
| Name | Parameters | Description |
|---|---|---|
| transcode | format, bitrate, framesize | |
| framegrabber | time | |
| fragment/timecrop | start, end / duration | embeds a fragment of a time-based media |
| resize | w, h | |
| crop | x, y, w, h | |
| youtubedownloader | format (code corresponding to youtube version to download) | |
| fadein | duration | fades in a time-based media |
| fadeout | duration | fades out a time-based media |
| zoom | enables a javascript zoom plugin for an image file (jquery iviewer?) | |
| thumbnail | w, h | creates a thumbnail (keeping ratio) of an image file |
| volume | integer | plays one file with the given volume |
| speed | x2, x4, -x2, -x4... | plays a time-based media with the given speed |
| controls | displays control buttons for a time-based media | |
| autoplay | autoplays a time-based media when it is triggered | |
| embed | html5 (default), html5audio | takes an audio/video ressource an wraps it in an audio/video element |
Exporters
Input: Playlist, Output: various
| Name | Output | Description |
|---|---|---|
| srtexport | text/srt | export titles to .srt format |
| feed | text/rss, atom? | export to RSS, ATOM feeds |
| mltscript | text/bash | |
| mltrender (*) | video/webm, ... | |
| svgmaker | text/svg | |
| audacity markers | text/plain | export to Audacity markers |
Walkthrough
Some URLs:
Sniff
Sniffing inspects a URL and displays "metadata" either contained within the resource, or indirectly available via the API of a web service. Sniffer plugins allow AA to be customized and extended to specific kinds of URL-based resources depending on the needs of an archive.
http://activearchives.org/aa/sniff/
To inspect the above URLs:
http://activeachives.org/aa/sniff/?url=http://video.constantvzw.org/vj12/Michael_Moss.ogv http://activeachives.org/aa/sniff/?url=http://www.youtube.com/watch?v=Wqh0HmMAa8c
Sniff tries all known sniffers on the URL, and collects and returns a list of URLs of specific sniffers with "something to say". Clicking on the individual link:
http://activeachives.org/aa/sniffers/youtube?url=http://www.youtube.com/watch?v=Wqh0HmMAa8c http://activeachives.org/aa/sniffers/ffmpeg?url=http://video.constantvzw.org/vj12/Michael_Moss.ogv
Yields an HTML+RDF page with speicific metadata and eventually links to "sub-sniffers" to get further metadata (such as youtube comments).
Crawl
In AA, crawling is the process of reading the contents of an (HTML) page, indexing its contents, and then to follow links and repeat the process (either automatically or guided manually by an editor).
Using the crawl URL:
http://activearchives.org/aa/crawl
Add the Sniff URL above to the aa Crawler / Indexer.
http://activearchives.org/aa/crawl?url=(http://activeachives.org/aa/sniffers/youtube?url=http://www.youtube.com/watch?v=Wqh0HmMAa8c)
(interactive mode? or follow all...)
AA starts at the sniff URL, then follows the links.
Evt: Archiving / snapshotting / versioning the contents will be part of the crawler.
Eventually optional support for both internal/external RDF stores.
Browse
AA provides a means of facet browsing crawled / indexed content of the archive.
- short/long form tabular form, javascript sortable
Wiki
Create a new page, make (semantic) links. Index these URLs by the Crawler
AA supports a simple markup to embed resources in a page. Embedding a resource adds it to the archive, thus enabling all the capabilities / support of the AA software.
{{ http://video.constantvzw.org/vj12/Michael_Moss.ogv }}
This embeds adds the resource to archive, sniffs it, crawls the pages. Uses RDF information to intelligently select a javascript delegate to include the resource on the page in a web accessible way.
The embed markup supports creating pipelines with filters. Filters are AA plugins that can be customized / extended and may implemented in any language (python / CGI, BASH).
{{ http://video.constantvzw.org/vj12/Michael_Moss.ogv | fragment start=01:00 duration=00:10 | transcode format=oggaudio }}
This embed has the effect of creates a new resource, which is then embedded into the referring page.
Annotate
There is a simple markup for annotating an embedded resource.
- Annotation markup makes it easy to create page fragments (div's) linked to resources (using RDF's @about).
- Beyond just establishing rdf triples, Annotation's are also about a having a compact unit of labelling (ie the context of the links/properties are important to preserve & work with). In this way AA extends rdf technology. (Is this the "context"?)
Current example of Michael Moss + Annotations: http://activearchives.org/aaa/resources/25/
(maybe have a generalized means of javascript-expanding a link within a page!)
- Is an annotation a kind of embed as well?
Playlist / Export
Search markup?
How to export modules fit in? (automatic table / list)?
How to make custom (django) views easy to create / mix in ?!
REST API
Core concepts: Resource, Page, Annotation, Playlist, Tags, Metadata (via typed links)
Goals,
- Have an API that corresponds to actual archive use, not over-generalizing.
- (related to this) Have an API that leads to meaningful/useful URLs like:
http://constantvzw.org/aa/images/ http://constantvzw.org/aa/recent/ http://constantvzw.org/aa/resource/127/thumbnail http://constantvzw.org/aa/resource/127/annotations http://constantvzw.org/aa/playlists/ http://constantvzw.org/aa/playlists/ http://constantvzw.org/aa/tags/vj13/ http://constantvzw.org/aa/tags/sarma/person/
Resource
A resource is the main item in an archive, it might be a video, an image, a webpage. Each resource is identified by a URL.
| URL | Method | Description |
|---|---|---|
| /resource/ID/annotations/ | GET | Get annotations, optional: start, end times filter by time range |
| /resource/ID/ | DELETE | Delete the resource and all associated metadata (annotations, playlists) |
| /resource/ID/ | POST | Add the given annotations |
| /resource/ID/ | PUT | Reset annotations to the posted annotations |
| /resource/ID/thumbnails/ | GET | Returns a list of available thumbnails |
| /resource/ID/versions/ | GET | |
| /resource/ID/tags/ | GET | Retrieve all tags for the resource |
| /resource/ID/tagsbytype/ | GET | The list of all tags organized by type for the resource |
| /resource/ID/tags/type/ | GET | Retrieve all tags of the given type for the resource |
| /resource/ID/metadata/ | GET | Retrieve all metadata for the resource |
| /resource/ID/metadata/NAME/ | GET | Get the associated values for the given name. |
| /resource/ID/metadata/NAME/ | PUT | Set the values for the given name. |
| /resource/ID/metadata/NAME/ | POST | Append values for the given name. |
Page
A wiki style page, page can be used to make annotations (among other things).
| URL | Method | Description |
|---|---|---|
| /page/PageName/ | GET | (Wikified page name), Get page contents |
| /page/PageName/annotations/ | GET | |
| /page/PageName/ | DELETE | Delete the resource and all associated metadata (annotations, playlists) |
Annotation
An annotation is like a note attached to a particular resource. Optionally, an annotation may be part of a playlist.
| URL | Method | Description |
|---|---|---|
| /annotation/ID/ | GET | |
| /annotation/ID/ | DELETE | Delete the annotation |
| /annotation/ID/ | POST | Append text to the given annotation |
| /annotation/ID/ | PUT | Set the text of the given annotation |
Playlist
A sequence of annotations. May be related to a number of Resources.
| URL | Method | Description |
|---|---|---|
| /playlist/ID/ | GET | |
| /playlist/ID/ | DELETE | Delete the playlist |
| /playlist/ID/ | POST | Append annotations to the given playlist |
| /playlist/ID/ | PUT | Set the annotations of the playlist |
Tag
Tags have resource, source, type, and value.
Tags can be organized as synonyms, and placed in hierarchies (via a parent property).
Source
Sources are used as the base of URLs for things like resources and tag types.
Flat structure of URLs with links ipv Hierarchy
