FlipStats API
This page describes the API for submitting hit and media information to the FlipStats system. This is an open API that anybody can implement to support our system and the plugins we offer are just implementations for various players or streamers that use this API.
This page is part of the ping plugin ticket and will be removed when the plugin is working.
How it works
The FlipStats API is RESTful - so it uses simple HTTP requests to both get and post data.
Submission format
Data is submitted in JSON format via an HTTP GET/POST. For example:
{
"user_key": "3xj2lKV0",
"players": {
"player_id": {
"runtime_version": "Flash 10.2.4.1",
"client_version": "JW FLV 4.5",
"streams": {
"filename1": {
"metadata": {
"width": 640,
"height": 480,
"duration": 67,
"container": "mp4",
"vcodec": "h264",
"bitrate": 768
},
"hits": [
{
"started": 1234567890,
"elapsed": 5.6,
"states": [
{
"name": "buffer",
"mediatime": 0.0,
"realtime": 0.0
},
{
"name": "play",
"mediatime": 0.0,
"realtime": 1.0
},
{
"name": "seek",
"pos": 14.4,
"mediatime": 2.4,
"realtime": 3.4
},
{
"name": "buffer",
"mediatime": 14.4,
"realtime": 3.4
}
{
"name": "play",
"mediatime": 14.4,
"realtime": 5.0
}
]
},
{
... another hit on the same stream ...
}
]
},
"filename2": {
... a hit on another stream ...
}
}
}
}
}
The above submission returns a session_id on success. Then later, as more time has passed:
{
"user_key": "3xj2lKV0",
"session_id": 12345,
"players": {
"player_id": {
"streams": {
"filename1": {
"hits": [
{
"started": 1234567890,
"elapsed": 15.6,
"states": [
{
"name": "pause"
"mediatime": 27.6,
"realtime": 18.2
}
]
}
]
},
... more files ...
}
}
}
}
The same session id is returned on success for all later submissions containing the session_id.
Available JSON fields
These fields are available:
Root
| Field | Description | Default |
| user_key | The key to the user under which account this hit is logged | required |
| session_id | Session-unique integer | required after first submission |
| players | Mapping of player id's to player data | required |
Players
| Field | Description | Default |
| runtime_version | The version of the runtime (Flash, Silverlight, etc) | null |
| client_version | The version of the client app being tracked | null |
| streams | Mapping of stream names to stream data | object |
Streams
| Field | Description | Default |
| metadata | Mapping of metadata attributes and values | object |
| hits | A list of hits to this stream from the given player id | array |
Hit
| Field | Description | Default |
| started | Timestamp of when stream was first ready | required |
| elapsed | The number of seconds of video time played | 0.0 |
| loaded_size | The number of bytes downloaded | null |
| states | A list of state changes with time information | array |
Note: elapsed and loaded_size may be more than the media duration or size, depending on if the user seeks backwards and how the client handles downloading the stream!
Metadata
| Field | Description | Default |
| title | The title of the media | null |
| duration | The duration of the media in seconds (-1 for live events) | null |
| size | The size of the media in bytes | null |
| container | The container format for the media | 'unknown' |
| bitrate | Average bitrate over the media stream in kbps (kbits) | null |
| vcodec | The video codec used | 'unknown' |
| width | The width of the video in pixels | null |
| height | The height of the video in pixels | null |
| framerate | The framerate of the video in frames per second | null |
| thumb | A remote path (HTTP) to the thumbnail for this video | null |
| acodec | The audio codec used | 'unknown' |
| channels | The number of audio channels | null |
Container
| Value | Description |
| unknown | The container format is not known |
| none | There is no container (e.g. MP3 file) |
| mp4 | Quicktime / MP4 / 3GP / F4V |
| avi | AVI |
| flv | Flash Video |
| mkv | Matroska |
| ogg | Ogg |
| mpegps | MPEG Program Stream |
| mpegts | MPEG Transport Stream |
| asf | Windows Media |
Vcodec
| Value | Description |
| unknown | The video codec is not known |
| none | There is no video (e.g. MP3 file) |
| h264 | H.264 / AVC / MPEG4 Part 10 |
| flv | Flash Video |
| flashsv | Flash Screen Video |
| vp6 | On2 VP6 |
| wmv | Windows Media Video / VC-1 |
| mpeg4 | MPEG 4 Video (Part 2) |
| mpeg2 | MPEG 2 Video |
| mpeg | MPEG Video |
| theora | Ogg Theora |
Acodec
| Value | Description |
| unknown | The audio codec is not known |
| none | There is no audio (e.g. video-only file) |
| mp3 | MP3 |
| aac | Advanced Audio Codec (AAC) |
| wma | Windows Media Audio |
| vorbis | Ogg Vorbis |
| pcm | Uncompressed Audio |
States
The states are a objects with various required parameters and optional parameters that depend on the type of state.
| Field | Description | Default |
| name | The name of the state (see below for possible values) | required |
| mediatime | The time in seconds as a float into the media stream | required |
| realtime | The time in seconds since this hit's started time | required |
The name values and other possible fields are listed below:
| Value | Parameters | Description |
| buffer | none | Media is loading and not currently playing |
| play | none | Media is currently playing |
| pause | none | Media is currently paused by user/script action |
| seek | pos:int | Seeking to new position in seconds |
| stop | none | Media playback has stopped |
| volume | level:float | Media playback volume has changed |
| mute | set:bool | Media playback volume was muted/unmuted |
| fullscreen | set:bool | Media playback was set to or from fullscreen |
| rate | percentage:float | Media playback rate has changed |
| bitrate | kbps:int | Media bitrate has dynamically changed |
For example, this means if you have a seek state it will look similar to:
{
"name": "seek",
"pos": 123,
"mediatime": 3.0,
"realtime": 3.5
}
API calls
The following calls describe the submission API:
| Call path | Parameters | Description |
| http://api.flipstats.com/submit | data:json | Submit a JSON object containing information about the media stream(s) |
