Camera Tag: Video Recording API & More!

In the past CameraTag would automatically generate three pieces of media for every recording that came in: an mp4, a small thumbnail and a large thumbnail. Users would have the option of choosing the resolution for the mp4 but beyond that you were limited to our predfined set of three file outputs.

With the release of v11 users now have much more control over the media(s) that the CameraTag transcoding farm will generate. You maay now create an many media outputs as you like. You also have full control over the type, resolution, format and watermark for each individual output. For example, here is a setup used by one of our v11 testers:

1 x 720p hls (no watermark)
1 x 720p mp4 with company watermark
2 x different size thumbnails with company watermark
1 x Automatic english language transciptions (for captions)
1 x 30 frame filmstrip for intractive

There are six types of outputs that you choose from. You can learn about each new type of output below and how it can be customized.

Videos
Images
Filmstrips
Audio
Waveforms
Transcriptions

Videos

For any Video input (usually from the <camera> tag) you can choose to have the CameraTag transcoding farm generate a video output. For each video output you create you may customize:

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "720p_with_company_watermak"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Resolution: This field allows you to specify the resolution of the video being generated. We have some predefined values setup for you (QVGA, VGA, 720p etc.) but you may also choose custom resolutions (if the apsect ratio differs from the original, the video will be padded to fit).

Max Length: This field allows you to specify the maximum length (in seconds) of the video file generated. This will automatically crop any sources longer than the specified length.

Extension: This field allows you to define the extension (and in-turn the codec) of the generated file. For videos the current options are mp4, webm, and m3u8 (HLS).

Overlay: You may optionally overlay an image on the generated video (think watermark or lower third). Simply provide a URL, width, height, top and left position for the image (you may position elemets in the lower right corner by using negative numbers in the top and left fields). Additionally you may use percentages in the height and width fields.

Images

For any Video or Photo input (usually from the <camera> tag or %ltphotobooth> tag) you can choose to have the CameraTag transcoding farm generate an image (thumbnail) output. For each image output you create you may customize:

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "half_size_thumb_with_watermark"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Resolution: This field allows you to specify the resolution of the image being generated. If the apsect ratio differs from the source media, the image will be padded to fit (black bars).

Offset: If the source media is a Video this parameter will allow you to define from what point in the video the thumbnal should be taken. This value can be given as a number of seconds or a percentage.

Extension: This field allows you to define the extension (and in-turn the codec) of the generated image. For images the current options are jpg and png.

Overlay: You may optionally overlay an image on the generated image (think watermark or lower third). Simply provide a URL, width, height, top and left position for the image (you may position elemets in the lower right corner by using negative numbers in the top and left fields). Additionally you may use percentages in the height and width fields of the overlay.

Images

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "half_size_thumb_with_watermark"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Width & Height: These fields allows you to specify the resolution of the image being generated. If the apsect ratio differs from the source media, the image will be padded to fit (black bars).

Offset: If the source media is a Video this parameter will allow you to define from what point in the video the thumbnal should be taken. This value can be given as a number of seconds or a percentage.

Extension: This field allows you to define the extension (and in-turn the codec) of the generated image. For images the current options are jpg and png.

Overlay: You may optionally overlay an image on the generated image (think watermark or lower third). Simply provide a URL, width, height, top and left position for the image (you may position elemets in the lower right corner by using negative numbers in the top and left fields). Additionally you may use percentages in the height and width fields of the overlay.

Filmstrips

For any Video input (usually from the <camera>) you can choose to have the CameraTag transcoding farm generate a filmstrip output. For each filmstrip you create you may customize:

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "filmstrip"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Resolution: All filmstrips have a fixed 300px width. Their height is dictated by the aspect ratio of the source media which you can define using the filmstrip's height and width parameters.

Extension: This field allows you to define the extension (and in-turn the codec) of the generated image. For filmstrps the current options are jpg and png.

Overlay: You may optionally overlay an image on the generated thumbnail (think watermark or lower third). This overlay will be placed on each frame of the filmstrip. Simply provide a URL, width, height, top and left position for the image (you may position elemets in the lower right corner by using negative numbers in the top and left fields). Additionally you may use percentages in the height and width fields of the overlay.

Audio

For any Video or Audio input (usually from the <camera> tag or %microphone> tag) you can choose to have the CameraTag transcoding farm generate an audio output. For each audio output you create you may customize:

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "mp3_audio_track"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Max Length: This field allows you to specify the maximum length (in seconds) of the audio file generated. This will automatically crop any sources longer than the specified length.

Extension: This field allows you to define the extension (and in-turn the codec) of the generated image. For images the current options are mp3, wav and aiff.

Waveforms

For any Video or Audio input (usually from the <camera> tag or %microphone> tag) you can choose to have the CameraTag transcoding farm generate an waveform output. This is a visual representation of the audio's waveform in image form. For each waveform output you create you may customize:

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "mp3_audio_track"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Waveform Color: This field allows you to choose the color of the weveform in the image (defined as an HTML hex value, for example #ff0000)

Width & Height: These fields allows you to specify the resolution of the waveform image being generated (in pixels)

Extension: This field allows you to define the extension (and in-turn the codec) of the generated image. For images the current options are mp3, wav and aiff.

Captions

For any Video or Audio input (usually from the <camera> tag or %microphone> tag) you can choose to have the CameraTag transcoding farm generate text cpations of the audio stream. This create a VTT formatted text file containing the words and timestamps of spoken words in the audio stream. These captions will automatically be made available as a captions overlay in the CameraTag player (audio and/or video assets). To create a transcription all you have to do is provide a media name and a language to detect:

The Media Name: This is a unique name uned to identify this particular output from the others (for example: "en_captions"). Note that because media names are used in URLs and JSON names must not conatin special characters or spaces.

Language: What language should we listen for / transcribe? The supported langages are:
- English (US)
- English (UK)
- French
- Spanish (ES)
- Chineese (ZH)
- Portuguese (BR)
- Arabic

Ads / Pre-Rolls

The CameraTag <player> has the ability to pre-roll content before your video or audio content. This content can come from one of two sources:

A CameraTag Video: You may specify the UUID of a CameraTag Video asset to be used as the <player> preroll content. In addition to the video uuid you may also specify:
- The Skip Offset: The number of seconds the user must watch the preroll before being allowed to skip
- Click URL: The URL to visit if / when the user clicks on the preroll
- Impression Tracking URL: A URL to hit when a user clicks on the preroll (for stats purposes)

A 3rd Party Ad Server You may chose to have a 3d party Ad Server serve up preroll ads before your content. CameraTag supports VAST, VPAID and Google IMA Ad Servers. Simply enter the URL of your Ad Server and you're off an running.

Custom Error / Processing Media

When an is transcoding, or has failed to transcode CameraTag will serve up a placeholder media. You can now use a CameraTag asset in your account as the transcoding and/or error placeholders. Simply supply the UUID of an existing asset you would like to use for each one of the custom placeholders.

Authorized Host

you may optionally provide one or more authorized hosts (domains) for your application. If you add an authorized host your App will only work with a camera embeded on that host or a subdomain of that host.

Every authorized host has an implicit wildcard before it (*.) so by adding mysite.com as an authorized host you would be authorizing *.mysite.com. This would allow video from a camera on mysite.com or subdomain.mysite.com.

The more specific you are with your authorized host the more restrictive. For example if you added subdmain.mysite.com as your authorized host the App would only accept videos embeded on subdmain.mysite.com (not mysite.com or somethingelse.mysite.com).

Publish Signature

When turned on only <camera> tags that contain valid data-signature and data-signature-expiration attributes will be allowed to publish videos to the server. The data-signature-expiration is a time (expressed in linux epoch format). The signatue is the HMAC-SHA1 hash of the data-signature-expiration with your API key. For example here is how you would generate the signature and signature expiration in Ruby:

expiration = (Time.now + 30.minutes).to_i
api_key = 'YOUR_API_KEY'
signature = OpenSSL::HMAC.hexdigest('sha1', api_key, expiration.to_s)

You would then use the culculated values in your <cmera> like so:

<camera id='[CAMERA_ID]' data-app-id='YOUR_APP_UUID' data-signature='CALCULATED_SIGNATURE' data-signature-expiration='EXPIRATION_IN_EPOCH_FORMAT'></camera>

This feature is only compatible with version 3 and higher of the JS Client. Ealier versions will always yield a signature error

Playback Signature

When turned on only <video> tags that contain valid data-signature and data-signature-expiration attributes will be allowed to play videos to the server. The data-signature-expiration is a time (expressed in linux epoch format). The signatue is the HMAC-SHA1 hash of the data-signature-expiration with your API key. For example here is how you would generate the signature and signature expiration in Ruby:

expiration = (Time.now + 30.minutes).to_i
api_key = 'YOUR_API_KEY'
signature = OpenSSL::HMAC.hexdigest('sha1', api_key, expiration.to_s)

You would then use the culculated values in your <video> like so:

<video id='[CAMERA_ID]' data-uuid='YOUR_VIDEO_UUID' data-signature='CALCULATED_SIGNATURE' data-signature-expiration='EXPIRATION_IN_EPOCH_FORMAT'></camera>

This feature is only compatible with version 6 and higher of the JS Client. Ealier versions will always yield a signature error

Wall Assets

This parameter determines which assets (if any) show up in <videowall>s that point to your app. The allowed values are: none, all, white list, black list. Whitelist will only display assets that in the "approved" or "featured" states. Blaick list will display all assets except those in the "rejected" state. Please be aware that all assets accessible to your wall should be assumed to be publicly accessible. Even if you only make your <videowall> visible to limited population, the API endpoint that supplies the wall with assets will be publicly accessible.

Crop Video Length

This parameter determines the maximum length of videos in the App. Uploded videos longer than the maximum length will be truncated to conform. Leave this value empty to have no limit on video length.

Email Notifications

Add an email address to this box to be notified whenever a user publishes a video using this camera. (you can send to multiple adresses by seprating them with a semicolon)

Webhooks

After a recording has been published it can take several seconds for your videos and thumbnails to be available. If you try to access the video or thumbnail URLs before they are finshed processing you will be served a placeholder image and/or thumbnail instead. If you need to be notified as to when axactly a video has finished processing you can use your CameraTag's server webhoook integration. As processing completes we will POST to a specified URL on your server with a JSON representation of your recording. Below is an example of a JSON representation of a recording that will be POSTed to your server:

{
  "uuid": "v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76",
  "preview_thumbnail_url": "https://www.cameratag.com/assets/v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76/720p_thumb.jpg",
  "preview_full_thumbnail_url": "https://www.cameratag.com/assets/v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76/720p_thumb.jpg",
  "preview_mp4_url": "https://www.cameratag.com/assets/v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76/720p_mp4.mp4",
  "preview_webm_url": "https://cameratag.com/videos/v-eed31052-1072-4457-bb62-aa49687e2be9/720p/mp4.mp4",
  "state": "processed",
  "name": "Bug Buck Bunny",
  "description": "A demo video",
  "type": "Video",
  "ad_server_type": null,
  "ad_server_url": null,
  "params": null,
  "app_uuid": "bd67aac0-7869-0130-7e72-22000aaa02b5",
  "medias": {
    "720p_mp4": {
      "width": 1280,
      "height": 720,
      "length": 32,
      "media_type": "mp4",
      "name": "720p_mp4",
      "state": "COMPLETED",
      "urls": {
        "cameratag": "https://cameratag.com/assets/v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76/720p_mp4.mp4"
      }
    },
    "720p_thumb": {
      "width": 1280,
      "height": 720,
      "length": null,
      "media_type": "thumb",
      "name": "720p_thumb",
      "state": "COMPLETED",
      "urls": {
        "cameratag": "https://cameratag.com/assets/v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76/720p_thumb.jpg"
      }
    },
    "720p_filmstrip": {
      "width": 1280,
      "height": 720,
      "length": null,
      "media_type": "filmstrip",
      "name": "720p_filmstrip",
      "state": "COMPLETED",
      "urls": {
        "cameratag": "https://cameratag.com/assets/v-1237c41f-9038-44b7-b4cc-8cb1f13f6f76/720p_filmstrip.jpg"
      }
    }
  }
}

Please note that the JSON repsonse is passed in the body of the POST and not as form parameters. Here is an example of how you would parse the response in ruby:

data = JSON.parse(request.raw_post)
video_uuid = data["uuid"]

S3 Bucket Name

The hosting of your recorded videos and thumbnails is part of your CameraTag plan. Sometimes, however, it's desirable to have the assets saved to your own servers as well. To accomplish this- enter the name of your Amazon S3 bucket in this field and we will save copies of all assets to your bucket as well.

PLEASE NOTE: In order for this to work you must either

Provide your AWS Key and Scret.
OR
Create a bucket policy granting us write access like the one below.

{
  "Version": "2008-10-17",
  "Id": "CameraTagBucketPolicy",
  "Statement": [
    {
      "Sid": "Stmt1295042087538",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::625596148923:root"
      },
      "Action": [
        "s3:GetObjectAcl",
        "s3:GetObject",
        "s3:PutObjectAcl",
        "s3:PutObject",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::MY-BUCKET/*"
    },
    {
      "Sid": "Stmt1295042087538",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::625596148923:root"
      },
      "Action": [
        "s3:ListBucketMultipartUploads",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::MY-BUCKET"
    }
  ]
}

FTP Server

CameraTag can automatically upload published assets to your FTP server. Simple provide us with the details we'll need to connect to your server and as soon as the assets are ready we'll copy them over to your box:

Protocol: (SFTP ot FTP)
Server: The host name (without protocol) of your ftp server (e.g. storage.myserver.com)
Directory: The subdirecory in which you would like files copied (user root by default)
Username: Username with write access to your server
Password: Password for the above username

YouTube

CameraTag can automatically copy published assets to your YouTube channel. Simply auhorize us to add videos to your account- you will be automatically redirected to YouTube when turning this feature on.