Blackmagic Video I/O Quick Start

In this Quick Start guide, we walk through the process of setting up an Unreal Engine Project to work with a professional video card from Blackmagic Design. At the end of this guide:

• you'll have video input from your Blackmagic card playing inside your Unreal Engine Project.
• you'll be able to capture camera viewpoints both from the Editor and from your runtime application, and send them out to an SDI port on your Blackmagic card.
• you'll know where to go when you want to set up more advanced adjustments to your video inputs, such as correcting lens deformation and applying chroma-keying effects.

For a working example that shows many of the elements described below put into practice, see the Virtual Studio showcase, available on the Samples tab of the Epic Games Launcher.

Prerequisites:

• Make sure that you have a supported card from Blackmagic Design, and that you've installed the necessary drivers and software. For details, see the Blackmagic Media Reference page.
• Make sure that your card is working correctly, and that you have some video input feeding in to at least one of the card's SDI ports.
• Open an Unreal Engine Project that you want to integrate with your video feeds. This page shows the steps in the Third Person Blueprint template, but the same steps will work equally well in any Project.

The Blackmagic Design components used in this guide are built on top of the Media Framework, and we'll use Blueprints to script the video capturing process at runtime. Some prior knowledge of these topics is recommended but not required.

1 - Set Up the Project

Before you can get video input from your Blackmagic card into your Unreal Engine Level, and send output from the Unreal Engine through one of your Blackmagic card's SDI ports, you'll need to do some basic setup to enable the Blackmagic Media Player Plugin in your Project.

If you started your Unreal Engine Project from one of the Templates in the Film, Television, and Live Events category, the necessary plugins may already be enabled for you. If not, follow the instructions below to enable them.

Steps

1. Open the Project that you want to use with Blackmagic video I/O in the Unreal Editor.

2. From the main menu, select Edit > Plugins.

3. In the Plugins window, find the Blackmagic Media Player plugin under the Media Players category. Check its Enabled checkbox.

   Click image to expand.

4. Find the Media Framework Utilities Plugin under the Media category. Check its Enabled checkbox, if it's not already checked.

   Click image to expand.

5. Click Restart Now to restart the Unreal Editor and reopen your Project.

   Click image to expand.

End Result

Your Project is now ready to accept video from the Blackmagic card, and to send rendered output to the card. In the next sections, we'll hook it up and start playing video in and out.

2 - Rendering Video Input in the Unreal Engine

In this process, we'll make video input from the Blackmagic card visible in the current Level in the Unreal Editor. This process uses a Media Bundle: a kind of Asset that packages together several different types of Assets involved in the Media Framework, and that offers you control over some advanced features like lens deformation, chroma-keying, color correction, and more. 

Steps

1. In your Content Browser, expand the Sources panel. Right-click, and choose New Folder from the context menu.

   

   Rename your new folder Blackmagic.

2. Open your new folder, right-click in the Content Browser and choose Media > Media Bundle.

3. Your new Asset's name is automatically selected in the Content Browser, so you can give it a descriptive name: Type a new name, like BlackmagicMediaBundle, and press Enter. A new folder of Media Framework Assets is automatically created next to your Media Bundle, named with the suffix _InnerAssets. We'll take a look at these Assets later.
4. Save your new Assets by clicking the Save All button in the Content Browser.

5. Double-click your new Media Bundle to edit its properties. The Media Bundle is capable of playing video from any kind of media source the Engine supports, so you'll need to tell it that you want to get the video from your Blackmagic card. In the Media Source property, select Blackmagic Media Source from the drop-down list:

   Click image to expand.

6. Once you've identified the type of Media Source you want the Media Bundle to handle, you can then set up any configuration properties offered by that type of source.  You can make Unreal Engine automatically match the format and framerate of the incoming video signal. To enable automatic format detection, click the Configuration dropdown, enable Auto, and then click Apply. The engine now seamlessly handles changes and restarts automatically if the signal is temporarily lost.

   Click image to expand.

   The options you see may vary depending on the devices you have installed. For details on all of the properties you can set for a Blackmagic Media Source, see the Blackmagic Media Reference page.

7. If you want to apply any compensation to the incoming video to account for lens distortion, you can set up the physical properties of the lens in the Lens Parameters section. 

   Click image to expand.

   These Lens Parameters just set up the physical properties of the lens. You'll actually activate the lens compensation later, when you edit the Material Instance used by the Media Bundle. Save and close your Media Bundle when you're done setting up its properties.

8. Drag your BlackmagicMediaBundle Asset from the Content Browser into the Level Viewport. 

   Click image to expand.

   You'll see a new plane appear, showing the video currently being played over the port configured for your Media Bundle. Use the transform tools in the Viewport toolbar to move, rotate, and resize it. If your Media Bundle doesn't start playing automatically, select it, then click the Media Bundle > Request Play Media button in the Details panel.

9. Now, we'll see how to apply keying and compositing effects to the video stream. Back in the Media Bundle Editor, click the Open Material Editor button in the Toolbar to edit the Material Instance that this Media Bundle uses to draw its incoming video feed on to an object in the Level.

   

   This Material Instance is saved inside the BlackmagicMediaBundle_InnerAssets folder that was created automatically with your Media Bundle.

   Click image to expand.

10. In the Material Instance Editor, you'll see a number of properties exposed for you to configure keying, cropping, and color correction, and to activate correcting for the lens distortion that you set up in the Media Bundle.

Click image to expand.

While you adjust the settings in the Material Instance Editor, you can see the effect of your changes on the video feed playing back in the main Level Viewport.

You may find it more convenient to see the effects of the changes you make in the preview panel of the Material Instance Editor instead. To do this, temporarily enable the IsValid setting, and set its value to 1.0.

Click the arrow at the top left of the viewport toolbar, and enable the Realtime option in the menu.

You'll be able to judge the effect of your changes more easily by changing the preview mesh to a plane or a cube. Use the controls at the bottom of the viewport:

When you're done, return the IsValid setting to its previous value.

1. When you're done changing the Material Instance properties, click the Save button in the Toolbar.

End Result

At this point, you should have video playing over an SDI port showing up inside your Unreal Engine Level, and you should understand where to set up more advanced features like lens deformation and chroma-keying.

If you're already familiar with the Media Framework, another way you could get video into your Level is to create a new BlackmagicMediaSource Asset in your Project, and set it up with the same source properties you set up inside the Media Bundle in the procedure above. Then, create your own MediaPlayer and MediaTexture Assets to handle the playback of that source in your Level. For details, see the Media Framework documentation. However, we recommend using the Media Bundle, as shown above, to get the best balance between ease of use and professional quality video features.

3 - Output Captures from the Unreal Editor

In this process, you'll set up an Blackmagic Media Output object, and use the Media Captures panel in the Unreal Editor to output the view from selected cameras in the Level to your Blackmagic card.

Steps

1. Right-click in the Content Browser, and select Media > Blackmagic Media Output. 

   Click image to expand.

   Name your new Asset BlackmagicMediaOutput.

2. Double-click your new Asset to open it up for editing. Just like when you created your Blackmagic Media Source, you have to set up the Configuration property to control the properties of the video feed that the Unreal Engine sends to your Blackmagic card. Click the arrow to open the submenu, select the options that match your video setup, then click Apply in the submenu. 

   Click image to expand.

   The options you see may vary depending on the devices you have installed. For details on all of the properties you can set in the Blackmagic Media Output, see the Blackmagic Media Reference page. Save and close your Media Output when you're done.

3. Now we'll place two cameras in the Level, to give us viewpoints for the output we'll send to the Blackmagic card. In the Place Actors panel, open the Cinematic tab, and drag two instances of the Cine Camera Actor into the viewport.

   

   Place the cameras where you want them in the Level, so that they're showing different viewpoints on the scene.

   Piloting the camera is a fast and easy way to set its viewpoint exactly the way you want it. See Pilot Actors in the Viewport.

4. From the main menu, choose Window > Virtual Production > Media Capture. You'll use the Media Capture window to control when the Editor sends output to your Blackmagic device, and what camera it should use in the Level.

   

5. Under the Media Viewport Capture area, find the Viewport Captures control. Click the Add (+) button to add a new capture to this list.

   

6. Expand the new entry. First, we'll add the cameras that we want to capture from. In the Locked Camera Actors control, click the Add (+) button to add a new entry.

   

   Then, use the drop-down list to choose one of the cameras you placed in the Level.

   

   Repeat the same steps to add the other camera to the list.

7. Now, set up the output that you want to capture these cameras to. Set the Media Output control to point to the new Blackmagic Media Output Asset that you created above. You can do this by selecting it in the drop-down list, or drag your Blackmagic Media Output Asset from the Content Browser and drop it into this slot.

   

8. At the top of the window, click the Capture button.

   

   You'll see a new frame at the bottom of the window that shows a preview of the output being sent to the Blackmagic card. If you have this port hooked up to another downstream device, you should start to see the output coming through.

   

9. Each camera that you added to the Locked Camera Actors list for this viewport capture is represented by a corresponding button above the video preview. Click the buttons to switch the capture back and forth between the two views.

   Click image to expand.

End Result

Now you've set up the Unreal Editor to stream output from cameras in your Level to a port on your Blackmagic card. Next, we'll see how to use Blueprint scripting to do the same thing in a running Unreal Engine Project.

4 - Output Captures at Runtime

The Media Capture window that you used in the last section is a practical and easy way to send captures to the Blackmagic card. However, it only works inside the Unreal Editor. To do the same thing when you're running your Project as a standalone application, you'll need to use the Blueprint API provided by the Media Output. In this procedure, we'll set up a simple toggle switch in the Level Blueprint that starts and stops capturing when the player presses a key on the keyboard.

The Virtual Studio showcase, available on the Samples tab of the Epic Games Launcher, contains a UMG interface widget that demonstrates how you could control capturing from an on-screen user interface.

Steps

1. From the main toolbar in the Unreal Editor, choose Blueprints > Open Level Blueprint.

   

2. We'll need to start from the Blackmagic Media Output Asset that you've created, where you identify the port you want to output to. In the Variables list in the My Blueprint panel, click the Add (+) button to add a new variable.

   

3. In the Details panel, set the Variable Name to BlackmagicMediaOutput, and use the Variable Type drop-down list to make it a Blackmagic Media Output Object Reference.

4. Enable the Instance Editable setting (1), and compile the Blueprint. Then, in the Default Value section, set the variable to point to the Blackmagic Media Output Asset that you created in your Content Browser (2).

5. Press Ctrl, and drag the BlackmagicMediaOutput from the Variables list in the My Blueprint panel into the Event Graph.

   

6. Click and drag from the output port of the BlackmagicMediaOutput variable node, and choose Media > Output > Create Media Capture. 

   

   Hook up your nodes to the Event BeginPlay node as shown below:

   

   This creates a new Media Capture object from your Blackmagic Media Output. The Media Capture offers two main Blueprint functions that we'll use to control the capturing: Capture Active Scene Viewport and Stop Capture.

7. First, we'll save the new Media Capture object into its own variable, so we can get access to it again elsewhere. Click and drag from the output port of the Create Media Capture node, and choose Promote to Variable.

   

   Rename the new variable MediaCapture in the Variables list in the My Blueprint panel.

   It's important to save the Media Capture to a variable here. If you don't, the Unreal Engine's garbage collector may destroy it automatically before you're done with it.

8. Press Ctrl and drag the MediaCapture variable into the Event Graph.

   

9. Click and drag from the output port of the MediaCapture variable node, and choose Media > Output > Capture Active Scene Viewport. Do it again, and choose Media > Output > Stop Capture.

   

10. Right-click in the Event Graph and choose Input > Keyboard Events > P.   Click and drag from the Pressed output of the P node and choose Flow Control > FlipFlop. 

1. Connect the A output of the FlipFlop node to the input event of the Capture Active Scene Viewport node, and connect the B output of the FlipFlop node to the input event of the Stop Capture node, as shown below:

1. Compile and save the Blueprint, and try playing your Project. Click the arrow next to the Play button in the main Toolbar, and choose either the New Editor Window (PIE) or Standalone Game option.

Video capture from the Editor will only work when you play your Project in a New Editor Window (PIE) or a Standalone Game. It won't work in the default Selected Viewport mode, or in Simulate mode. In addition, the viewport resolution of your Project (that is, the size of the rendered image the Unreal Engine generates each frame) must match the output resolution set in the active Media Profile, so that it will be the right size for the output video feed.

After your project starts up, you should be able to press the P button on your keyboard to toggle sending the output from the Engine to the Blackmagic card.

End Result

At this point, you should have a basic idea of how to work with Blackmagic Media Sources, Media Bundles, and the Media Capture system, and you should understand how all of these elements work together to get professional video in and out of the Unreal Engine.

On Your Own

Now that you've seen the basics of how to get a new Project exchanging video input and output with a Blackmagic card, you can continue learning on your own:

• Explore the in-engine keying solution in the Material Instance created by your Media Bundle. Try passing some green-screen video into your card's input port, and use the keying controls in the Material Instance to remove the background.
• Explore the Virtual Studio showcase to see what it adds to this basic setup, like its on-screen UI that switches cameras and controls video capture at runtime.