# Unity ```eval_rst .. _unity: ``` ## Version and OMS Player Install The OMS Player Package supports Unity version 2018.4(LTS). To create a new project using the Unity OMS Player, first create a new unity project.you can house multiple projects and their OMS/MP4 files in a single OMS Player scene. With your new Unity project open, you can select Import Package > Custom Package and import the OMS Player 2020.4.unitypackage located in your HoloSuite 2020.4 install directory, and import all assets when prompted. ## Unity Package Contents The OMS Player Package will add several new folders to your project, including a StreamingAssets folder with sample data for use with the OMS Player, and an Arcturus.Volumetric folder containing the volumetric plugin and associated content and scripts. The following content is included: ### Arcturus.Compression Required scripts related to OMS compression and playback. ### Arcturus.Dash Required scripts related to OMS compression and playback. ### Arcturus.Volumetric - **Examples**: Data required for the bundled Example Scenes. - **Animations**: Animations required for example scenes. - **Prefabs**: Prefabs used in example scenes. - **Scenes**: Example scenes for OMS setup and playback. - **Streaming**: Assets and scripts used in the Streaming examples. - **UI**: Assets and scripts used for UI in the example scenes - **Materials**: Materials used in examples or in OMS Playback. - **NativeVideo**: Required scripts related to OMS compression and playback. - **OMSPlugin**: Required scripts related to OMS compression and playback - **Prefabs**: OMS Player Prefabs for use in user created scenes. See example scenes for examples of prefab usage. - **Scripts**: Various scripts related to OMS Playback and OMS Player configuration. - **Shaders**: Shaders used for OMS Playback. - **Textures**: Data textures used for some OMS Playback features. - **Timeline**: Scripts related to scheduling and playback. ## OMS Player Script The OMS Player Script can be applied to any GameObject and configured to turn that object into an OMS Player. The OMS Player script contains the following settings: ### Default Render Config The Default Render Config drawer sets the default render options for all clips in the selected OMS Player. It contains the following options: - **Material**: Set the Material for use in the OMS Player. You can choose any OMS Player material, such as SkinnedMeshMaterial or SkinnedSurfaceMaterial. - **Tint**: Specifies a tint color for this material. Default white results in no tint. - **Shadow Casting Mode**: Set Shadow Casting to On, Off, Two Sided, or Shadows only. ### Playback Mode The Playback Mode determines how the underlying OMS Playback functions, mostly switching how different data streams (geometry, texture, audio) are loaded. For most projects Automatic is recommended to choose the best playback mode for your target platform. Playback mode contains the following options: - **Video Player**: Read textures and audio from a video file using Unity’s built-in VideoPlayer component. - **Native Video**: Read textures and audio from a video file using a platform-specific (“native”) plugin. The OMS Player package includes plugins for several platforms, including OSX, iOS, and Android - **Automatic**: Automatically selects between “Video Player” and “Native Video” depending on the targeted platform per build. - **Texture**: Reads textures from a series of .png files, does not read audio. - **None**: Does not read textures or audio. - **Stream**: Reads geometry and textures from a HoloStream URI. ### Hide Video Player Hides any components spawned at runtime to handle video playback, if you find them distracting. ### Clock Determines the source of the clock used to advance through the frames of an OMS. The default option, Video Time, is recommended for most projects. Playback mode contains the following options: - **Video Time**: Syncs geometry playback with the current texture frame from the corresponding video file (see “Video Filename” in [Clips](clips)).The Playback Mode field must be set to VideoPlayer, NativeVideo, or Automatic, and a video file must be provided. - **Unity Time**: Displays the frame corresponding to how much time has elapsed since playback was started, as measured by Unity’s Time.time property. - **Mecanim Progress**: Displays the frame corresponding to the time elapsed in the linked Mecanim animation (see “Mecanim State Name” in [Clips](clips)). Note: Mecanim playback is EXPERIMENTAL as of HoloEdit 2020.4. - **None**: Does not automatically advance the frame. The frame must be controlled manually through the OMSPlayer API (FrameUpdate, StepForward, StepBackward). ### Clip Directory Determines the default directory for clip files. If left empty, the clip directory used will be “Assets/StreamingAssets”. The Oms Filename, Video Filename, and Textures Path values are relative to the configured Clip Directory. ### Clips ```eval_rst .. _clips: ``` The Clips drawer contains an array of per Track configuration for each clip included in the OMS Player. Setting the “Size” Value greater than zero generates one or more Clip drawers for configuration. - **Element**: Clip Drawers labeled “Element [Clip Number]” are generated for each Clip specified by the Size value. This drawer’s name will update to reflect the name of the clip when the OMS Filename is configured (see below). Each Clip Drawer contains the following fields: - **Oms Filename**: The path and filename (including extension) to the OMS file used for playback. This path is relative to the Clip Directory field, and by default relative to the “StreamingAssets” folder in your Unity Project. For example, If the Clip Directory is left blank and your OMS file called “file.oms’ is located in the “Assets/StreamingAssets” directory, you would enter “file.oms” in this field. - **Video Filename**: The path and filename (including extension) to the video file used for playback. Like the OMS Filename, this path is relative to the Clip Directory field, and by default relative to the “StreamingAssets” folder in your Unity Project. For example, If the Clip Directory is left blank and your video file called “file.mp4” is located in the “Assets/StreamingAssets” directory, you would enter “file.mp4” in this field. - **Textures Path**: Used only with “Textures” playback mode. Path to a directory in Resources, relative to the Resources directory, containing the textures to use. For example, if your textures are located in “Assets/Resources/myTextures”, this should be set to “myTextures”. Textures are associated with frames by sorting by name in a platform-specific manner. For the most predictable results, textures should be named numerically and padded with leading zeroes (e.g. “0000.png”, “0001.png”, “0002.png”) - **Mecanim State Name**: If specified, the OMSPlayer should automatically switch to this clip when the matching AnimationController changes to the state with the same name. Note: Mecanim playback is EXPERIMENTAL as of HoloEdit 2020.4. - **Track Configs**: This provinces configuration for [MultiTrack](multi-track-export) OMS playback. MultiTrack OMS files can contain multiple actors, each on a separate “Track” that can be configured individually. Setting the “Size” Value greater than zero generates one or more Track Drawers for configuration labeled “Element [Track Number]”. Track Drawers contain the following fields: - **Material Override**: Allows you to specify any OMS player material for this Track only, separate of the overall OMS Player material specified in the Default Render Config. - **Tint**: Allows you to specify a per-Track Tint separate from the Default Render Config Tint. - **Retarget**: Enable or disable Retargeting for this Track. - **Skeleton Root**: Specify the Skeleton Root for use with Retargeting. If Retarget is disabled this setting has no effect. - **Skeletal Base Movement**: Specify the base animation file for use with Retargeting. If Retarget is disabled this setting has no effect. - **Experimental**: Experimental clip level settings - **Enable Fast Loading**: Speeds up loading of OMS files by skipping a step where the maximum vertex and index count are determined from the contents. If enabled you must manually configure Max Vertex Count and Max Index count to be at least as high as the maximum value in any mesh in the clip. If the value is too low, the OMS will fail to load and the application may crash. - **Max Vertex Count**: Size of preallocated vertex table. - **Max Index Count**: Size of preallocated index table. Each triangle needs 3 indices. ### Loop Toggles looping playback on all clips and Tracks in this OMS Player. ### Ping Pong Toggles Ping Pong (backwards and forwards loop) playback on all clips and Tracks in this OMS Player. ### Draw Editor Label Toggles display of an OMS Player label in the Unity Scene View. The label appears at the position of the OMSPlayer object, and contains two values. The “F” value shows which overall frame is currently being displayed. The “S” value shows which segment the current frame belongs to. ### Timeline and Sync ```eval_rst .. _timeline-and-sync: ``` Fields related to syncing unity animations with OMS Playback. Contains the following fields: - **Drive Timeline**: If enabled, the specified Timeline will have its time set to the OMSPlayer’s current time every frame while the OMSPlayer is playing. - **Timeline**: The timeline selected for Drive Timeline. - **Video Carries Audio**: Unimplemented in HoloEdit 2020.4.1. - **Video OMS Offset Start**: Subtracted from the video frame when determining what geometry frame to use. Typically Used to allow a video file to contain an audio-only prelude before texture/geometry playback begins. Only functions when PlaybackMode is set to NativeVideo. ### UI Events Emitted by OMSPlayer as various internal events happen. Create Listeners to update custom components. - **OnClipLoaded**: The clip with the given index has been loaded. - **OnPlayStateChanged**: Player state has changed to the given state. - **OnPlayTimeChanged**: The current playback time has changed to the given time (seconds). - **OnBuffertimeChanged**: The amount of buffered-ahead content has changed to the given time (seconds). Streaming mode only. - **OnPlayError**: Playback has failed with the given error message. ### Other Events - **OnIKNeeded**: The OMSPlayer fires this event when it is time for IK solvers to modify the pose of the retargeting skeleton. ### Animation Sync Unity Animations in your project can be synchronized with OMS playback using a shared Timeline. To drive a Timeline with an OMS player, configure the [Timeline and Sync](timeline-and-sync) settings to drive a timeline containing your animations. ### OMS Player Materials The OMS Player Package contains two Materials for use with the OMS Player. These materials should be used with the Default Render Config and Material Override settings on an OMS player. #### SkinnedSurfaceMaterial The SkinnedSurface material is a surface shader that exposes the Albedo texture (driven by the OMS player), smoothness, and metallic values, in addition to a color tint (driven by the OMS player per-track). #### SkinnedMeshMaterial The SkinnedSurface material is an unlit shader that exposes the Albedo texture (driven by the OMS player) in addition to a color tint (driven by the OMS player per-track). ## OMS Player Configuration example The following is a walkthrough of a typical OMS Player configuration: OMS and MP4 data for use in the OMS player must be located inside of the StreamingAssets directory, in the root or a subfolder of your choosing. All OMS and MP4 files used for playback must be located in the StreamingAssets folder. Player Configuration is provided by the 'OMS Player' script. To use an OMS player, add the script to a new GameObject in your scene. ```eval_rst .. image:: assets/unityomsplayerexample.png :width: 500 ``` Several fields will need to be updated in the OMS Player component: 1. Under Default Render Config, ensure the Material is set to SkinnedMeshMaterial (or another material created for rendering OMS files.) and that Playback Mode is set to Automatic. 2. In the Clips drop down, set the Size to 1 or more, which exposes fields for your OMS and MP4 file locations. Most .oms files will contain one clip, but Multitrack OMS exports (see [MultiTrack Export](multi-track-export) ) contain multiple clips, which can each be configured separately if the Size value is set to a value greater than 1. 3. OMS Filename and MP4 Filename fields must include the local path to your OMS fils, including the '.OMS' or'.MP4' extension(i.e. [subfolder]/[filename].OMS) 4. Ensure ‘Loop’ is enabled for continuous looping playback. Once you have updated your OMS Player component, ensure you have both Scene and Game windows visible, and press ‘Play’ in the Unity editor.