TheArtCollider API Documentation

This page describes Services that are provided by TheArtCollider Infrastructure. For example: automatic thumbnails generation; or creating playlists from available streams.

The Yellow Pages Directory can be asked for list of active Sources. This information can be exported in various formats:

• Atom/XML Syndication format: http://theartcollider.net/yp/feed?type=atom
• M3U/Text Playlist: http://theartcollider.net/yp/feed?type=m3u
• XSPF/XML: XML Shareable Playlist Format: http://theartcollider.net/yp/feed?type=xspf
• inoutC2 (deprecated): backwards-compatible XML for previous InOut Projects: http://theartcollider.net/yp/ioxml

The m3u file is easy to parse (MaxMSP/Jitter, Processing) text and is understood my a multitude of A/V players (eg. VLC) and Pure data‘s readanysf external has native support for m3u-playlists. The shortcoming of m3u is that it does not include any meta-data (Author, Number of listeners, etc.).

The Atom feed and XSPF are approved w3c standards, understood by any XML parser (fi. your web-browser). They provide (most) meta-data provided for each stream.

The YP-feed interface can be used search the Directory and filter results: The base-url http://theartcollider.net/yp/feed accepts the query parameter q to look up streams by tag.

q is a list of space separated tag-names. A stream will be included in the result list if it contains any of the give tags.

eg.

http://theartcollider.net/yp/feed?type=atom&q=audio
http://theartcollider.net/yp/feed?type=atom&q=tag
http://theartcollider.net/yp/feed?type=atom&q=tag1%20tag2

TheArtCollider automatically generates previews for each of the connected streams. You need to specify either the SID (from the feed-listing) or the stream-url as parameter. It will reply a PNG image.

eg.

http://theartcollider.net/yp/thumb.php?url=http://r32142.ovh.net:8000/footage4.ogg
http://theartcollider.org/yp/thumb.php?sid=b6f0e3eb209ac8fbee9dff79a383008b

The image is cached for up to 30 seconds. If you need to get more frequent screen-shots, you can add the url-query parameter timeout=<seconds>; where <seconds> is an integer between 4 and 30 to get more recent snapshots:

  http://theartcollider.org/yp/thumb.php?sid=b6f0e3eb209ac8fbee9dff79a383008b&timeout=5

Currently Images are provided cropped as fixed size of 575×280 pixels.

Most programming environments these days provide an API to retrieve data via HTTP and also to parse standardized formats. Yet it may still come in handy to use command-line tools for testing and debugging:

curl - is an utility to transfer a URL. It is available out-of-the-box on Unix systems (Linux, Mac-OSX). You can either save the output to a file or get it on standard-output:

Examples:

save a PNG:

curl -o /tmp/test.png http://theartcollider.net/yp/thumb?sid=68dec0308fe123482f6688d50981b87e

get a playlist of all sources:

curl http://theartcollider.net/yp/feed?type=m3u

download a playlist of all sources with the tag InOut

curl -o /tmp/tac.m3u http://theartcollider.net/yp/feed?type=m3u&q=InOut

save 20 seconds of video-data:

curl -s http://theartcollider.org:8002/example1.gv -o /tmp/grab.ogv -m 20 --show-error --fail

More elaborate command-line examples are described in the technical documentation section.

TheArtCollider uses the icecast Yellow Pages protocol to collect available A/V sources.

The endpoint for submitting information is http://theartcollider.net/yp/

You can add any icecast server to TheArtCollider network by specifying a directory-server in your icecast.xml configuration file:

  <directory>
      <yp-url-timeout>15</yp-url-timeout>
      <yp-url>http://theartcollider.net/yp/</yp-url>
  </directory>

Connections are kept track of by matching IP addresses of subscribers and publishers via the yellow-pages system.

In general this works nicely but has two shortcomings:

• multiple projects run on the same server (or NAT network) can not be distinguished
• update latencies exist for fast switching projects (icecast2 only sends yellow-page updates ~60seconds)

To circumvent these issues projects can directly announce their connections to the yellow-pages system. By doing so the automatic connection monitoring for the IP that does the announcement is disabled for 5 mins.

You submit your connection information by sending requests to

http://theartcollider.org/yp/tell?<parameters>

In parameters you need to include a source-stream ID (what you read), your output stream ID and optionally a mode: add/del (add being the default).

The streams can be identified either by title: srcname=<name>, URL: srcurl=<url> or stream-id: srcsid=<hex-id>. Similar your output stream needs to be specified as either name=<name>, URL: url=<url> or stream-id: sid=<hex-id>. Adding mode=del removes a connection rather than adding one.