Up and Running with the Oddworks Server

by Patrick McConnell

Oddworks is an OTT or video distribution server. If you want to run your own television 2.0 empire here is how to get started.

Before you can start building your Roku, Android or iOS apps to showcase your awesome video content you need to get a server up and running to distribute your content. Think of Odd Networks as the Death Star to support your media empire (forgetting what those pesky rebels did in the end.)

To get started visit our Github repo and download or clone a copy of the Oddworks code. The server code is a Nodejs application so it should run on any OS capable of running Node apps. If you are only interested in writing client applications for the iPhone or Roku, etc and don’t know Node or Javascript, don’t worry you don’t need to know anything to get started.

Once you have a copy of the Oddworks code on your computer navigate to the folder that contains the code. The first command to run will be:

npm install

NPM is the Node Package Manager and it will install all the other pieces of the Oddworks puzzle required to run the server.

You will see the progress displayed as npm installs all the projects dependencies to your hard drive.

Once that completes run:

npm run setup

This command will setup all the environment variables and configure a command line application you will use to generate tokens needed by the server to allow API access.

If you were to fire up the server right now with:

npm run dev

the Oddworks server will spring to life and be ready for your commands (or at least your API requests)

However you will most likely be frustrated trying to talk to the server until you understand some basic concepts.

Let’s start with a few terms we use here at Odd Networks.

Channel

A channel is just like on plain old regular tv. It’s the main organizational structure for your content.

Platform

A platform is the type client you wish to allow access to your content via the API. So you will need a platform entry for Roku, Android, iOS, AppleTV, etc.

Authentication Token

In order to verify that a platform trying to access the API should be allowed access we check a few values and one of these values is a token that is unique to the channel and platform making the request. We provide a tool to generate these tokens as will be explained below.

If you have gotten this far with the installation you will notice you didn’t install any other software (outside of the node modules installed via npm.) While Oddworks can support many pluggable modules that will use third party tools such as search tools and databases, the initial install is configured to get you up and running as easily as possible.

When you ran

npm run setup

earlier, you configured the basic developer version of the Oddworks server.

This instance of the server has an in-memory data store and some basic data is loaded from JSON files off your drive. These files are stored under the data folder. You will notice folders for a few things we have already discussed such as Platforms, Channels and others like Videos and Collections.

To customize the data available to the server you can edit and/or add to these files.

A note about video assets: Oddworks does not host the video content you will be linking to. We host the metadata including links to your video and image assets. You will need to have those assets hosted in a publicly accessible manner.

To get up and running quickly you can link to videos on public hosting sites such as YouTube or Vimeo. Naturally, once you want to put your media empire into general circulation, you will need to have your content hosted with a provider designed to handle this task such as Ooyala or JWPlayer.

You won’t want to run a production server by editing JSON files from your hard drive either. At that point you would want to use one of our plug-ins for a data store such as Mongo or Redis.

Ok. With those caveats out of the way lets get you up and running with the final steps.

You should have an existing Channel and Platform in the appropriate Data folder. You can use the samples provided or create new files in the same format.

To see the available tokens run the following command:

oddworks token-list

This will go through the data folders finding any Devices you have defined and print out the token for each. Copy the token for use in your client apps or to test with Curl or Postman.

If you made any changes to your data such as adding a platform or channel, and the server is already running you can kill it (control-c) and restart it with:

npm run dev

Once the server is running and you have your authentication token you can begin to use the Oddworks API. If you want to check that things are working you can run this Curl command in your terminal:

curl -X GET -H “x-access-token: <YOUR TOKEN HERE>” -H “Accept: application/json” “http://localhost:3000/"

Make sure the actual token string is one that exists.

You should get a response that looks like this:

{ “data”: 
    { “attributes”: 
        { “message”: ”Server is running” }
    },
    ”links”: {
        “self”:”http://localhost:3000/"
    },
    "meta": {
        "channel": "odd-networks",
        "platform":"APPLE_IOS"
    }
}

The key thing is that line that says the server is running. You can also see that it recognized your token as belonging to the channel and platform that it was generated for.

The other important thing to notice is that the Oddworks server only handles JSON requests at this time. So you need to be sure to add a header as follows:

“Accept: application/json”

We also check that you are authorized to view any data associated with your channel so you must include this header as well:

“x-access-token: <your authentication token>"

At a minimum both of these two headers must be present in any request made to the Oddworks API.

A more useful request might give you a list of all the videos in the system;

curl -X GET -H “x-access-token: <YOUR TOKEN HERE>” -H “Accept: application/json” “http://localhost:3000/videos"

Which will return something like this:

{
 “data”: [
  {
    “id”: “continuous-live-stream”,
    “type”: “video”,
    “relationships”: {
    “related”: {
    “data”: []
 }
 },
 “meta”: {
 “entitlements”: []
 },
 “attributes”: {
 “sharing”: {
 “enabled”: true,
 “text”: “Watch the @oddnetworks show Live on mobile and TV connected devices!”
 },
 “channel”: “odd-networks”,
 “title”: “Live TV”,
 “description”: “”,
 “images”: {
 “aspect16x9”: “http://dummyimage.com/16:9x1440&text=Live TV”
 },
 “url”: “https://devimages.apple.com.edgekey.net/streaming/examples/bipbop_16x9/bipbop_16x9_variant.m3u8”,
 “closedCaptions”: “”,
 “duration”: 60000
 },
 “links”: {
 “self”: “http://localhost:3000/videos/continuous-live-stream”
 }
 },
 {
 “id”: “daily-show-video-1",
 “type”: “video”,
 “relationships”: {
 
 ...

You will get a list of all the videos in your data store. You can see above many of the meta fields we provide out of the box, but naturally you can edit this information to better match your needs.

If you are experimenting with client apps to play videos you will take note of the Video having a Title, Description, Images and URL fields. These will come in handy with almost any media application.

Note the images can be an array of images at different sizes and aspect ratios to best match your needs.

The URL is the actual media asset that you will play.

Hopefully after reading this far you have Oddworks installed on your computer, you have configured a device, and you are ready to start developing client applications to access Oddworks.

Remember Oddworks, our SDKs and sample code is all available and open source. Feel free to bend it to your will.

Please join us in our Slack channel to get help or share what you have built.

We can’t wait to see the awesome media applications you create.

Thanks to Matt Barth.