simpleVID Support

Contact Us

If you have any problems with our application you can use the form below to contact the author.

Spam filter
Message
 

simpleVID channel format description

This document describes actual simpleVID channel JSON format. If you used simpleVID before you may notice some small differences with old JSON format which is still supported but deprecated therefore we recommend using new JSON format described here.

simpleVID channel is a JSON with a following base structure:

{
  "comment":"comments about the channel",
  "svChannel":{
    "name":"channel name",
    "version":"channel version string",
    "title":"channel title visible to the user",
    "image":"channel image url (recommended size 320x180)",
    "screens":[]
  }
}

Optionally channel can also contain params field for channel parameters or userAgent field for setting user agent http header as in the example below:

{
  "comment":"comments about the channel",
  "svChannel":{
    "name":"channel name",
    "version":"channel version string",
    "title":"channel title visible to the user",
    "image":"channel image url",
    "userAgent":"custom user agent",
    "params":[
      {
        "name":"Observed search:",
        "param":"{observedSearch}",
        "required":true
      }
    ]
    "screens":[]
  }
}

Screens is an array of screen objects which describe what content (links) should be visible on given screen and what those links open. Links on a screen can link to another screen or to a video file or stream. Screen has a following base structure:

{
  "name":"main",
  "title":"screen title visible to the user",
  "link":"url related to the screen (for regex)",
  "image":"screen image url",
  "info":"additional description",
  "content":[]
}

Name of the screen is used to link one screen to another. Screen with a special name "main" is the main screen that should be showed as the first screen.

Content is an array of content objects which describe links visible on given screen. There are two types of content objects that is static and dynamic.

Basic static content object has following structure:

{
  "type":"static",
  "nextScreen":"videoPlayer",
  "title":"link title",
  "link":"link url",
  "image":"link image url",
  "info":"link description"
}

Type field specifies if this is a static or dynamic content object and nextScreen specifies the name of the screen that should be opened by selecting this link or if it is set to a special value "videoPlayer" then it means that the link points to a video stream and should be opened in the video player instead of presenting a new screen. Link is a link to a video stream or a web page url that should be passed to the next screen. Link can also contain parameters that user will need to enter if he selects this link. To specify what parameters user should enter and where to put them in the link you use additional params parameter as in the example below. Note that in case you want to use a global channel parameter in a link then you also must redeclare this global channel parameter with the same name in this section that you actually want to use it in a link.

{
  "type":"static",
  "nextScreen":"searchResults",
  "title":"link title",
  "link":"https://www.randomwebsite.com/results?q={search}",
  "image":"link image url",
  "info":"link description",
  "params":[
    {
      "name":"Search for",
      "param":"{search}",
      "urlEncoded":true
    }
  ]
}

Note that urlEncoded parameter above is optional and by default is true. Link field can also have extended form that is instead of having simply an url from which you download html it can also specify if this url should be used in a POST or GET (default) request. If you need to perform a POST request for example to perform a search by filling a html form then you can use extended link form where: first line is url same as in the simple form, second line is GET or POST keyword, next lines are optional http headers, after optional headers there must be an empty line, after empty line is http body. Note that when you use extended link form then returned html will additionally contain http headers returned by the server. Below is an example which demonstrates how you can use an extended link to perform a search through http input form which has an input with name "key" instead of adding search query to the url as in previous example.

{
  "type":"static",
  "nextScreen":"searchResults",
  "title":"link title",
  "link":"https://www.randomwebsite.com/results\nPOST\n\nkey={search}",
  "image":"link image url",
  "info":"link description",
  "params":[
    {
      "name":"Search for",
      "param":"{search}",
      "urlEncoded":false
    }
  ]
}

Additionally in case when you want to first download a html from a link parameter and then extract a single link to a video stream with a regular expression you can use regexVideoPlayer parameter together with nextScreen set to videoPlayer value. In the example below simpleVID will first download html from randomwebsite link and then extract a single link to a stream with given regular expression and open video player with that stream.

{
  "type":"static",
  "nextScreen":"videoPlayer",
  "title":"link title",
  "link":"https://www.randomwebsite.com/superChannel.html",
  "image":"link image url",
  "info":"link description",
  "regexVideoPlayer":{ "regex":"mpegurl=\"(http.*?)\"", "link":"$1" }
}

More advanced stream extraction with regular expressions can be done with dynamic content objects which can extract many links from a single html page.

Basic dynamic content that uses regex has following structure:

{
  "type":"dynamic",
  "nextScreen":"videoPlayer",
  "regex":"<img src=\"(.*?)\"[\\s\\S]*?<h3><a href=\"(.*?)\">(.*?)</a></h3>",
  "title":"$3",
  "link":"$2",
  "image":"$1",
  "info":"$2"
}

While using a dynamic content object you specify regular expression in regex field that will extract parts of htmls that contain titles, links and optionally image urls or additional info text descriptions from the data downloaded from the link related to the screen object. In this regular expressions you then can use capturing groups to extract titles, links, images or infos from matched patterns as in the example above. While using regular expressions you must notice that due to internal parsing a single \ sign from regex is preceeded with another \ sign and " inside regex also needs to be proceeded with a \ sign to not break the json format. On the other hand a / sign should not be proceeded with a \ sign. Additionally you can use filters to post process the data extracted with regex as in the example below.

{
  "type":"dynamic",
  "nextScreen":"videoPlayer",
  "regex":"<img src=\"(.*?)\"[\\s\\S]*?<h3><a href=\"(.*?)\">(.*?)</a></h3>",
  "title":"$3",
  "link":"$2",
  "image":"$1",
  "info":"$2",
  "filters":[
    {
      "op":[
        "replace",
        "title",
        "360p",
        "Low quality (360p)"
      ]
    }
  ]
}

Filters are applied in the same order as stored in the json. Each filter has at least two parameters. First parameter is the name of the filter and second is the name of the field to which filter should be applied. There are few possible filters and each of them can be applied to title, link, image and info. See examples below.

Find and replace filter:

{
  "op":[
    "replace",
    "title",
    "360p",
    "Low quality (360p)"
  ]
}

Find and replace with regex filter:

{
  "op":[
    "regexReplace",
    "info",
    "duration=\"(.*?)\"",
    "Duration: $1"
  ]
}

Add prefix filter:

{
  "op":[
    "prefix",
    "link",
    "yourPrefix"
  ]
}

Add suffix filter:

{
  "op":[
    "suffix",
    "image",
    "yourSuffix"
  ]
}

Uppercase filter:

{
  "op":[
    "uppercase",
    "title"
  ]
}

Lowercase filter:

{
  "op":[
    "lowercase",
    "title"
  ]
}

Hex encoding filter:

{
  "op":[
    "hexEncode",
    "link"
  ]
}

Hex decoding filter:

{
  "op":[
    "hexDecode",
    "link"
  ]
}

Percent encoding filter:

{
  "op":[
    "percentEncode",
    "link"
  ]
}

Percent decoding filter:

{
  "op":[
    "percentDecode",
    "link"
  ]
}

After creating your custom channel we recommend validating your json first with an online tool such as JSON Formatter & Validator website to make sure that json is parsing properly. Also we recommend another online tool that is RegExr website which can help you with creating proper regular expressions for your channel. Note however that you will need to slightly modify regular expressions for simpleVID in case they contain signs such as: \, ", / Currently there is no special tool or way to debug created channels. The recommended way of creating and testing a svChannel is to create a http server on your computer and host a file with a channel on it while having autoupdates enabled in simpleVID for this channel. This way changes made in json file saved on your computer can be automatically refreshed in simpleVID app by going back to the menu and opening the channel again. For debug purpose title or info fields can be used to see the results of used regular expressions and filters on the screen before using them on link or image fields.

A complete example of a simpleVID channel could look like below:

{
  "comment":"simpleVID Abstract fractals channel",
  "svChannel":{
    "name":"abstractFractals",
    "version":"1.0",
    "title":"Abstract fractals",
    "image":"http://mytestwebsite.com/abstract/Blue%20abstract.jpg",
    "params":[
      {
        "name":"Observed search:",
        "param":"{observedSearch}",
        "required":false
      }
    ],
    "screens":[
      {
        "name":"main",
        "title":"Abstract fractals",
        "link":"http://mytestwebsite.com/abstract/",
        "image":"",
        "content":[
          {
            "type":"static",
            "nextScreen":"searchResults",
            "title":"SEARCH",
            "link":"http://mytestwebsite.com/abstract/search.php?s={search}",
            "image":"",
            "params":[
              {
                "name":"Search for:",
                "param":"{search}"
              }
            ]
          },
          {
            "type":"static",
            "nextScreen":"searchResults",
            "title":"OBSERVED SEARCH",
            "link":"http://mytestwebsite.com/abstract/search.php?s={observedSearch}",
            "image":"",
            "params":[
              {
                "name":"Observed search should be configured from main menu first!",
                "param":"{observedSearch}"
              }
            ]
          },
          {
            "type":"dynamic",
            "nextScreen":"abstractDetails",
            "regex":"<img src=\"(.*?)\"[\\s\\S]*?<h3><a href=\"(.*?)\">(.*?)</a></h3><p>.(.*?).</p>",
            "title":"$3",
            "link":"$2",
            "image":"$1",
            "info":"Duration: $4"
          }
        ]
      },
      {
        "name":"searchResults",
        "content":[
          {
            "type":"static",
            "nextScreen":"",
            "title":"Search results:",
            "link":"",
            "image":""
          },
          {
            "type":"dynamic",
            "nextScreen":"abstractDetails",
            "regex":"<img src=\"(.*?)\"[\\s\\S]*?<h3><a href=\"(.*?)\">(.*?)</a></h3><p>.(.*?).</p>",
            "title":"$3",
            "link":"$2",
            "image":"$1",
            "info":"Duration: $4"
          }
        ]
      },
      {
        "name":"abstractDetails",
        "content":[
          {
            "type":"dynamic",
            "nextScreen":"videoPlayer",
            "regex":"<a href=\"(.*?)\">(360p|480p|720p)</a>",
            "title":"$2",
            "link":"$1",
            "filters":[
              {
                "op":[
                  "replace",
                  "title",
                  "360p",
                  "Low quality (360p)"
                ]
              },
              {
                "op":[
                  "replace",
                  "title",
                  "480p",
                  "Medium quality (480p)"
                ]
              },
              {
                "op":[
                  "replace",
                  "title",
                  "720p",
                  "High quality (720p)"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

In addition to plain JSON format simpleVID channels can also be encoded with a standard base64 encoding. Base64 encoded channels can be detected by simpleVID inside HTML code which means that you can use them to provide a simpleVID channel for your website on the main page of your website instead of creating a separate file with a raw JSON on your server in order to provide a simpleVID channel for your website. Base64 encoded channels must start and end with a special BEGIN/END SVCHANNEL tags in order to be detected by simpleVID app. Below is an example of a channel in base64 format that will be automatically detected by simpleVID if you enter the link to this page inside simpleVID app.

-----BEGIN SVCHANNEL-----
eyJjb21tZW50Ijoic2ltcGxlVklEIElQVFYgVEVTVCBDSEFOTkVMIiwic3ZDaGFubmVsIjp7Im5hbWUi
OiJpcHR2VGVzdENoYW5uZWwiLCJ2ZXJzaW9uIjoiMS4wIiwidGl0bGUiOiJCNjQgVEVTVCBDSEFOTkVM
IiwiaW1hZ2UiOiJodHRwOi8vb21vbW9tby5jb20vaXB0dnRlc3QucG5nIiwic2NyZWVucyI6W3sibmFt
ZSI6Im1haW4iLCJ0aXRsZSI6IkI2NCBURVNUIENIQU5ORUwiLCJsaW5rIjoiIiwiaW1hZ2UiOiIiLCJj
b250ZW50IjpbeyJ0eXBlIjoic3RhdGljIiwibmV4dFNjcmVlbiI6InZpZGVvUGxheWVyIiwidGl0bGUi
OiJUZXN0IDEiLCJsaW5rIjoiaHR0cDovL29tb21vbW8uY29tL3N0cmVhbS90ZXN0MS5tM3U4IiwiaW1h
Z2UiOiJodHRwOi8vb21vbW9tby5jb20vc3RyZWFtL3Rlc3QxLnBuZyIsImluZm8iOiJMaXZlIHN0cmVh
bSB2aWRlbyB0ZXN0IGNoYW5uZWwifSx7InR5cGUiOiJzdGF0aWMiLCJuZXh0U2NyZWVuIjoidmlkZW9Q
bGF5ZXIiLCJ0aXRsZSI6IlRlc3QgMiIsImxpbmsiOiJodHRwOi8vb21vbW9tby5jb20vc3RyZWFtL3Rl
c3QyLm0zdTgiLCJpbWFnZSI6Imh0dHA6Ly9vbW9tb21vLmNvbS9zdHJlYW0vdGVzdDIucG5nIiwiaW5m
byI6IkxpdmUgc3RyZWFtIGF1ZGlvIHRlc3QgY2hhbm5lbCJ9XX1dfX0=
-----END SVCHANNEL-----

Note that whitespace characters inside this format are optional and can be removed.