Adding Logo Overlays to Videos with the Media API

Product
Video Cloud
Applies to Roles
Developer
Version
Brightcove 5
Modules
Media API
Edition
Pro, Enterprise
Created by Grant Goodman.

A logo overlay is a small, often partly transparent, image that displays over a corner of a video. Logo overlays are a useful tool that can help reinforce your brand online and drive traffic back to your website. Each image can have a click-through link associated with it, which you can use to drive traffic to your site or promote a specific page. Video Cloud provides several different approaches to adding logos to your videos:

  • You can set a default logo overlay for your account using the Account Settings page in the Video Cloud Studio.
  • You can set a logo overlay for one or more videos using the Media module, FTP batch provisioning, or the Media API's add_logo_overlay method
  • You can set your account so that a burned-in logo gets added to all of your video files when they are uploaded and transcoded. In most cases, you don't want to use both a logo overlay and a burned-in logo for the same video.

This topic describes how to use the Media API's add_logo_overlay method to assign a logo overlay to an existing video. You can add new logo overlays (by uploading a file or supplying a remote-asset URL) or you can assign an existing logo overlay to a video. The add_logo_overlay method returns the LogoOverlay object that was added to the video (regardless of whether you were creating a new LogoOverlay, updating an existing one, or just using an existing one without updating it). You can also remove a logo overlay from a video using the remove_logo_overlay method.

For information about creating logo overlay images, see Adding Logos to Your Videos.

The add_logo_overlay method

The Media API Reference describes all the parameters used with the add_logo_overlay method. The Media API Objects Reference describes all the properties of the LogoOverlay object that is created or updated, and returned, by the add_logo_overlay method. This method has the following signature:

add_logo_overlay(token:String, logooverlay:LogoOverlay, 
          filename:String, maxsize:Long, 
          file:InputStream, file_checksum:String, 
          video_id:Long, video_reference_id:String):LogoOverlay

This is a write method, so use the Media API write token for your account.

In the add_logo_overlay method, certain parameters are conditionally required:

  • If you are creating a new logo overlay, you must provide either a file (with maxsize and filename) or a remoteUrl (as a property on the LogoOverlay).
  • If you are not creating a new asset, you must provide either the id or the reference_id of an existing logo overlay (as a property on the LogoOverlay).
  • You must provide either the video_id or the video_reference_id of the video to which you want to add the logo overlay.

Adding a logo overlay using a remote image files

The standard way to create logo overlays is to upload them to the Video Cloud servers. If your account is enabled for remote assets, you can instead keep your logo overlay asset on your own server and use the remoteUrl property of the LogoOverlay's image property to tell Video Cloud where to find the image. For more information about remote assets, see Creating Videos with Remote Video Files.

The remove_logo_overlay method

You can remove a logo overlay from a video using the remove_logo_overlay method. This method just removes the association between the logo overlay and the specified video; it does not delete the logo overlay or affect any other videos the logo overlay may be assigned to. The Media API Reference describes all the parameters used with the remove_logo_overlay method. This method has the following signature:

remove_logo_overlay(token:String,  
          video_id:Long, video_reference_id:String):void

This is a write method, so use the Media API write token for your account. Pass in either the Video Cloud video ID or reference ID of a video along with your token, and the video will no longer have a logo overlay assigned to it.

add_logo_overlay examples

Here are several examples that demonstrate how to use the add_logo_overlay method:

In addition, see this complete example using JavaScript.

Uploading and assigning a new logo overlay

This example assumes that you are uploading an image file using a multipart/form-data POST. The file_checksum is optional; if it is supplied and the checksum of the uploaded file doesn't match, you will get a 308 NonmatchingChecksumError. If the uploaded file is not a GIF or PNG file, you will get a 306 FileFormatError. The video_id property indicates that we want to assign the new logo overlay to the video with id 17035.

{
    "method" : "add_logo_overlay",
    "params" : {
        "token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
        "logooverlay" : {
            "image" : {
                "referenceId" : "wicklow-1",
                "displayName" : "Wicklow Corp. logo",
                "type" : "LOGO_OVERLAY"    },
            "tooltip" : "Click the bunny to win!",
            "linkURL" : "http://wicklow.example.com/bunny",
            "alignment" : "TOP_LEFT"        },
        "file_checksum" : "d1c9c2b112993a0079a0128ecb9b36dd",
        "video_id" : 17035
    }
}

After you submit the JSON in this example, the add_logo_overlay method returns the following:

{"result": {"displayName":"Wicklow Corp. logo","id":30300017070001,
            "referenceId":"wicklow-1","remoteUrl":null,"type":"LOGO_OVERLAY"},
 "error": null, "id": null}

Creating a new logo overlay with a remote asset

In this case we're supplying a remoteUrl, so we don't have to upload a file. If you try to create a remote asset and that feature is not enabled for your account, your Media API call will return a 309 RemoteAssetsDisabledError. For more information about remote assets, see Creating Videos with Remote Video Files.

{
    "method" : "add_logo_overlay",
    "params" : {
        "token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
        "logooverlay" : {
            "image" : {
                "referenceId" : "still-1",
                "displayName" : "first remote still",
                "type" : "LOGO_OVERLAY",
                "remoteUrl" : "http://www.example.com/images/logoOverlay1.jpg"    },
            "tooltip" : "Click the bunny to win!",
            "linkURL" : "http://wicklow.example.com/bunny",
            "alignment" : "TOP_LEFT"        },
        "video_reference_id" : "video-2"
    }
}

Updating an existing logo overlay

In this example, we supply the referenceId of a logo overlay asset that already exists and update the existing logo overlay with the file at the new remoteUrl. The type is not required in this case because we already know the type of the asset. In fact, even if we had supplied a type, and changed it to LOGO_OVERLAY, this would have no effect as you can't change the type of an existing asset.

We could have supplied the Video Cloud id of the logo overlay instead of the referenceId.

Note that we still have to supply a video_id or video_reference_id for the video that this logo overlay is assigned to. This is always required. In this case we don't want to assign the asset to any other video, so we just supply the referenceId of the video that already uses this logo overlay.

{
    "method" : "add_logo_overlay",
    "params" : {
        "token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
        "logooverlay" : {
            "image" : {
                "referenceId" : "logoOverlay-1",
                "remoteUrl" : "http://www.example.com/public/images/logoOverlay1.jpg"    },
            "tooltip" : "Click the bunny to win!",
            "linkURL" : "http://wicklow.example.com/bunny",
            "alignment" : "TOP_LEFT"
        },
        "video_reference_id" : "video-2"
    }
}

 

Tags
bug, dog, logo overlay