```eval_rst
.. _8th-wall:
```

# Example 8th Wall Player
8th Wall is a development platform for creating web-based AR content. 8th wall can be deployed on any platform that supports WebAR or WebVR.

The A-Frame: HoloStream [8th Wall](https://www.8thwall.com/) (external link) project contains a minimal [A-Frame](https://aframe.io/docs/1.3.0/introduction/) (external link) Three.js scene playing HoloStream content in 8th wall. Refer to the [Three.js](https://threejs.org/) (external link) and [HoloStream API](https://learn.arcturus.studio/docs/holostream/en/v2021.1/html/Holostream_API/api.html) documentation for details on individual functions and components.

<video width="100%" nocontrols autoplay loop onloadedmetadata="this.muted = true">
  <source src="../../../../shared/_images/Ewan_8th_Wall.webm" type="video/webm">
</video>


## Getting Started
This document contains steps to get started and an overview of the A-Frame: HoloStream project. The fastest way to get your HoloStream into 8th wall is by using the A-Frame: HoloStream project template.


### Cloning the 8th Wall HoloStream Project template
From the [my projects page](https://www.8thwall.com/my-projects) of the 8th Wall site, click the **Start a new project** button. This will open the new project page. Select your workspace, project URL, and license type according to your needs. For more information, see the [Start a New Project](https://www.8thwall.com/docs/web/#start-a-new-project) section on the 8th Wall Documentation.
Once you are finished, click the **Create** button.

![alt_text](Assets/8th_Wall_Create.png "8th Wall Project Creation Page")

This will bring you to the quick start page. Click on the **8th Wall Templates** tab to open the templates selection menu. In the search field, type in HoloStream. Then click on the **A-Frame: HoloStream** template, and click the **Clone Project** button on the template details screen. This will create a clone of this template that you can modify to suit your needs.

![alt_text](Assets/8th_Wall_Template.png "8th Wall Template Page")


### Acquiring your HoloStream .mpd URL
The next step in setting up your 8th Wall project is to get your HoloStream .mpd URL. If you have one already, you can continue to the next step. If you don't yet have one, please take a look at the [Upload to HoloStream](https://learn.arcturus.studio/docs/holostream/en/v2021.1/html/Exporting_HoloStreams/Uploading_From_HoloEdit.html) section of the docs for instructions on exporting your HoloEdit project to HoloStream.


### Reviewing in the 8th Wall Editor
Now that you have cloned the project, you will be taken to the 8th Wall editor. In the 8th Wall editor, you can review and edit the code of the A-Frame project. The holostream-component.js file contains the code to import the HoloStream using the [HoloStream API](https://learn.arcturus.studio/docs/holostream/en/v2021.1/html/Holostream_API/api.html#api) and manage the A-Frame scene.

![alt_text](Assets/8th_Wall_Editor.png "8th Wall Template Page")

In the head.html file 8th wall tags and external scripts are initialized. The HoloStream API is imported in a `<script>` tag.

In the body.html file the A-Frame scene is configured, along with a camera and several a-frame entities. The HoloStream player is added to the A-Frame scene with the id "holo", and the [.mpd URL](https://learn.arcturus.studio/docs/holostream/en/v2021.1/html/HoloStream_Basics/HoloStream_Basics.html#manifest-url) to the HoloStream Clip.

To change the HoloStream clip, replace the default URL (**"https://holostream-dev.arcturus.studio/media/23f517e8-a10e-48ae-bc76-8ccde959937d/stream/dash/manifest.mpd"**) With the URL for your HoloStream clip.

![alt_text](Assets/8th_Wall_URL.png "8th Wall URL")

```
```important::
Be sure to use the URL ending in .mpd, and not a HoloStream preview URL ending in the GUID for a HoloStream clip.
```


### Previewing your Project
To preview your 8th wall project, click **Save + Build** to build the project. Once it is built you can click **Preview** at the top of the screen. This will give you a QR code that you can scan to open a preview of your project on a phone or tablet.

```
```note::
You can select debug mode here if you are looking for more information on the performance of your 8th wall project.
```

After launching the 8th wall project on your mobile device, you'll be ready to preview your HoloStream clip. Because of the code in the holostream-component.js file, you will need to tap the screen to select a flat surface in order to place the HoloStream clip.

You should now see your HoloStream clip displayed. You can pinch to scale the HoloStream clip, touch and drag to reposition it, and rotate it by dragging with two fingers.


## Landing
If your HoloStream looks good when you preview it, then you are ready to land your 8th Wall project. The 8th Wall editor uses a source control-like method for managing changes. This lets you land changes to your code in the same way you would commit when using source control. To do this, click the **Land** button in the top right of the editor. This will prompt you to leave a commit message before you are able to click the **Land Files** button at the bottom right.

![alt_text](Assets/8th_Wall_Land.png "8th Wall Land screen")


## Publishing
 Now that your changes are landed, you are ready to publish. To do this click the **Publish** button in the top right corner of the editor. This will open the publish screen. Here you can select the commit and privacy for your published project. Staging will allow you to publish with a password, allowing it to be shared, but not accessed by the public. Select your most recent commit and desired privacy setting before clicking the **Publish** button. Lastly you will be prompted to configure the details for the project. Fill in the project title, cover image (optional), and details (optional) before clicking the **Done!** button. You will then be presented with a direct link that can be used to access the published project.

![alt_text](Assets/8th_Wall_Publish.png "8th wall pubish screen")


## Controlling the 8th wall project
In body.html, an A-frame scene and multiple entities are declared. The logic for the holostream-entity object is contained in `HoloStream-Component.js`. A HoloStream instance is configured correctly and created, and the HoloStream mesh is drawn in the 8th wall scene. The rest  of the component's logic is general 8th wall and A-Frame functionality.


### Initializing a HoloStream Instance
```
    const holoStreamOptions = {
      debugEnabled: false,
      targetCanvasID: '',
      threeScene: this.el.sceneEl.object3D,
      threeCamera: cameraElement.object3D,
      threeRenderer: this.el.sceneEl.renderer,
      hideUI: true,
      overrideRender: true,
      showPlayButtonOnLoadingScreen: false,
    }

    this.holoStream = new HoloStream(holoStreamOptions)
    this.holoStream.openURL(this.data.url)
```

The HoloStream player is configured by supplying the existing A-Frame SceneEL, cameraElement, and renderers as parameters to the Options object in the HoloStream [Constructor](https://learn.arcturus.studio/docs/holostream/en/v2021.1/html/Holostream_API/api.html#api-constructor). Then, the holostream mpd url supplied as `src` in the body.html file is opened.


### Drawing the HoloStream Mesh
in the `placeHoloGram` event, the `holoStream.getThreeMesh()` function is used to assign the streaming mesh to the element with `this.el.object3D.add(mesh)`. The mesh is placed according to the touch event, and is set to play back with `this.holoStream.handlePlay(true)`.


## Image Tracking
We provide another 8th wall template scene that allows you to create an image-tracked Volumetric clip. In our template a trading card is being used for tracking by default, but this could be changed to be a business card, poster, packaging or any other trackable image.

You can check out this template in action [here](https://arcturus.8thwall.app/holostream-image-tracking/).


### Cloning the template
You can use the [Image Tracking Template](https://www.8thwall.com/arcturus/duplicate-project/arcturus/holostream-image-tracking) to clone the project.


### HoloStream link
As before you will want to change the streaming .mpd link in the body.html file. This time the HoloStream-hologram can be found as a child of the `xrextras-named-image-target object`. This lets the volumetric clip transform in relation to the position, rotation, and scale of the tracked image. Change the .mpd URL after the `src=` line to match your .mpd.


### Transform
You can then adjust the position and rotation of your clip in relation to the tracked image using the `rotation` and `position` attributes below the src attribute. You can also add in a `scale` attribute if you need to adjust the scale of the volumetric clip.


### Image Target
To test out this project, you can simply use the image on the image targets screen to trigger the tracking. To use your own image as an image target, simply upload a new image target in the image target screen. This screen can be found in the tabs to the left, and has a target icon. If your new tracked image has a different name, you will need to change the name attribute of the `xrextras-named-image-target` to match the name of the new image target you have uploaded.

```
```note::
    Autoplay: Due to Apple's autoplay restriction, in order to have the clip play when the target image is found, the audio must start muted. If your clip has audio, ensure this.hasAudio of the holostream-component is set to true. This will cause a tap to unmute prompt to show at the bottom.
```


### Components
```<holostream-hologram>``` Is the HoloStream clip.
`src:` This must be updated to the mpd URL for your HoloStream.
```<xrextras-named-image-target>``` represent the tracked image once it is located.

Because the `holostream-hologram` component is a child of the `xrextras-named-image-target`, it will copy its positional data, moving it with the card once tracked.

`name:` This is the name of the image target as it appears on the "Image Targets" page

Learn more about Image Targets here:
[documentation](https://www.8thwall.com/docs/web/#image-targets).


## Further Learning
This is the basics of using HoloStream clip with 8th wall. For more information, reference the [HoloStream API](https://learn.arcturus.studio/docs/holostream/en/v2021.1/html/Holostream_API/api.html) documentation, along with the [8th Wall](https://www.8thwall.com/docs/),  [A-Frame](https://aframe.io/docs/1.3.0/introduction/), and [THREE.js](https://threejs.org/docs/index.html#manual/en/introduction/Creating-a-scene) documentation.