simpleVID Support

Contact Us

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

Email
Subject
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, however 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",
    "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. Alternatively instead of "videoPlayer" you can use "videoPlayer1" if system video decoder is prefered or "videoPlayer2" if alternative video decoder is prefered. 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. 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,info"
  ]
}

Lowercase filter:

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

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: \, ", /

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",
    "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":"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)"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}