diff --git a/wiki/ALVR-client-and-streamer-on-separate-networks.md b/wiki/ALVR-client-and-streamer-on-separate-networks.md index 7dd69e6373..82b7609681 100644 --- a/wiki/ALVR-client-and-streamer-on-separate-networks.md +++ b/wiki/ALVR-client-and-streamer-on-separate-networks.md @@ -6,9 +6,9 @@ Here are explained two methods to connect PC and headset remotely, port-forwardi ## Important notes on security -* ALVR protocol does not have any encryption or authentication (apart from ALVR client IP address shown in ALVR streamer and the requirement to add client on ALVR streamer). -* It is recommended to run ALVR via encrypted tunnel (VPN) over the internet. In case VPN is not an option, access to ALVR streamer (UDP ports 9943 and 9944) should be restricted by Windows Firewall (only connections from known IP addresses of ALVR clients should be allowed) and ALVR streamer should not be left running unattended. -* **Warning!** SteamVR allows to control desktop from VR headset (i.e. a **malicious ALVR client could take over the PC**). +* ALVR protocol does not have any encryption or authentication (apart from ALVR device IP address shown in ALVR streamer and the requirement to add devices on ALVR streamer). +* It is recommended to run ALVR via encrypted tunnel (VPN) over the internet. In case VPN is not an option, access to ALVR streamer (UDP ports 9943 and 9944) should be restricted by Windows Firewall (only connections from known IP addresses of ALVR devices should be allowed) and ALVR streamer should not be left running unattended. +* **Warning!** SteamVR allows to control desktop from VR headset (i.e. a **malicious ALVR device could take over the PC**). * As the license states ALVR IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND (see the file `LICENSE` in this GitHub repository for legal text/definition). You are on your own (especially if you run ALVR over the Internet without VPN). ## Port-forwarding @@ -23,7 +23,7 @@ Port-forwarding allows to connect devices that are behind different NATs, i.e. l You can now use ALVR to connect to your remote PC. -**Note**: The public IP can change often. Every time you want to use ALVR you need to check that your current public IP is the same as the last time. If the IP changed, you can update it using the "Configure client" interface, accessed with the `Configure` button next to your headset name on the streamer. +**Note**: The public IP can change often. Every time you want to use ALVR you need to check that your current public IP is the same as the last time. If the IP changed, you can update it using the "Edit connection" interface, accessed with the `Edit` button next to your headset name on the streamer. ## ZeroTier diff --git a/wiki/Building-From-Source.md b/wiki/Building-From-Source.md index 07f8a29858..90eb7b8bbd 100644 --- a/wiki/Building-From-Source.md +++ b/wiki/Building-From-Source.md @@ -70,7 +70,7 @@ If you want to edit and rebuild the code, you can skip the `prepare-deps` comman ## Fedora CUDA installation -If you are here for CUDA installation on Fedora you're at the right place! Else continue down to [Client Building](https://github.com/alvr-org/ALVR/wiki/Building-From-Source#client-building) +If you are here for CUDA installation on Fedora you're at the right place! Else continue down to [Android App Building](https://github.com/alvr-org/ALVR/wiki/Building-From-Source#android-app-building) ### 1. Install Nvidia drivers and Fedora CUDA driver @@ -145,11 +145,11 @@ From the ALVR directory edit the ./alvr/xtask/src/dependencies.rs, and change tw You should be good to go! Refer to [Streamer Building](https://github.com/alvr-org/ALVR/wiki/Building-From-Source#streamer-building) for the commands to build ALVR -# Client Building +# Android App Building ## 1. Installing necessary packages -For the client you need install: +For the app you need install: * [Android Studio](https://developer.android.com/studio) or the [sdkmanager](https://developer.android.com/studio/command-line/sdkmanager) * Android SDK Platform-Tools 29 (Android 10) @@ -224,7 +224,7 @@ Move to the root directory of the project, then run this command: cargo xtask prepare-deps --platform android ``` -Before building the client, Android has to have us to agree to the licenses otherwise building the client will halt and fail. To accept the agreements, follow the instructions for your corresponding OS: +Before building the app, Android has to have us to agree to the licenses otherwise building the app will halt and fail. To accept the agreements, follow the instructions for your corresponding OS: * Windows: @@ -240,7 +240,7 @@ Before building the client, Android has to have us to agree to the licenses othe sdkmanager --licenses ``` -Next up is the proper build of the client. Run the following: +Next up is the proper build of the app. Run the following: ```bash cargo xtask build-client --release diff --git a/wiki/Configuration-Information-and-Recommendations.md b/wiki/Configuration-Information-and-Recommendations.md index bd7578e161..6e967b5495 100644 --- a/wiki/Configuration-Information-and-Recommendations.md +++ b/wiki/Configuration-Information-and-Recommendations.md @@ -47,7 +47,7 @@ ## Routing / Switching / Firewalling / General Info -- Ideally client and streamer should exist on the same logical (layer 2) network and subnet - this allows for no routing overhead, and the correct function of client discovery via [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) +- Ideally the headset and streamer should exist on the same logical (layer 2) network and subnet - this allows for no routing overhead, and the correct function of device discovery via [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) - Twisted pair (normal copper ethernet cables) should never be run alongside power cables - this can cause signal noise and result in frame loss and lowered auto-negotiation speeds - High quality CAT5E or higher (ideally CAT6A or CAT7) gigabit+ cabling should be used for modern networks - In some cases firewall, anti-virus, malware, or EDR (enhanced detection and response) software may interfere with network traffic - Windows Defender and Sophos Endpoint Protection are reported to work without issue diff --git a/wiki/How-ALVR-works.md b/wiki/How-ALVR-works.md index 6ad5cec08f..6c9b89996c 100644 --- a/wiki/How-ALVR-works.md +++ b/wiki/How-ALVR-works.md @@ -21,11 +21,11 @@ This document was last updated on June 27th 2023 and refers to the master branch * Driver communication * Driver lifecycle * The streaming pipeline: Overview -* Client-driver communication +* Device-driver communication * Discovery * Streaming * SteamVR driver -* Client and driver compositors +* Device and driver compositors * Foveated rendering * Color correction * Video transcoding @@ -40,29 +40,29 @@ This document was last updated on June 27th 2023 and refers to the master branch ### The packaged application -ALVR is made of two applications: the streamer and client. The streamer can be installed on Windows and Linux, while the client is installed on Android VR headsets. The client communicates with the driver through TCP or UDP sockets. +ALVR is made of two applications: the streamer and device. The streamer can be installed on Windows and Linux, while the device app is installed on Android VR headsets. The device app communicates with the driver through TCP or UDP sockets. -The client is a single unified APK, named `alvr_client_android.apk`. It is powered by OpenXR and it is compatible with Quest headsets, recent Pico headsets and HTC Focus 3 and XR Elite. +The app is a single unified APK, named `alvr_client_android.apk`. It is powered by OpenXR and it is compatible with Quest headsets, recent Pico headsets and HTC Focus 3 and XR Elite. The streamer is made of two main parts: the dashboard and the driver (also known as server). The driver is dynamically loaded by SteamVR. This is the file structure on Windows: * `bin/win64/` - * `driver_alvr_server.dll`: The main binary, responsible for client discovery and streaming. Loaded by SteamVR. + * `driver_alvr_server.dll`: The main binary, responsible for device discovery and streaming. Loaded by SteamVR. * `driver_alvr_server.pdb`: Debugging symbols * `openvr_api.dll`: OpenVR SDK used for updating the chaperone. * `vcruntime140_1.dll`: Windows SDK used by C++ code in the driver. -* `ALVR Dashboad.exe`: Dashboard binary used to change settings, manage clients, monitor statistics and do installation actions. It can launch SteamVR. +* `ALVR Dashboad.exe`: Dashboard binary used to change settings, manage devices, monitor statistics and do installation actions. It can launch SteamVR. * `driver.vrdrivermanifest`: Auxiliary config file used by the driver. At runtime, some other files are created: -* `session.json`: This contains unified configuration data used by ALVR, such as settings and client records. -* `session_log.txt`: Main log file. Each line is a json structure and represents an event generated by the driver. This gets cleared each time a client connects. +* `session.json`: This contains unified configuration data used by ALVR, such as settings and device records. +* `session_log.txt`: Main log file. Each line is a json structure and represents an event generated by the driver. This gets cleared each time a device connects. * `crash_log.txt`: Auxiliary log file. Same as `session_log.txt`, except only error logs are saved, and does not get cleared. ### Programming languages -ALVR is written in multiple languages: Rust, C, C++, HLSL, GLSL. The main language used in the codebase is Rust, which is used for the dashboard, networking, video decoding and audio code. C and C++ are used for graphics, video encoding and SteamVR integration. HLSL is used for graphics shaders on the Windows driver, GLSL is used on the Linux driver and the client. Moving forward, more code will be rewritten from C/C++ to Rust and HLSL code will be moved to GLSL or WGSL. +ALVR is written in multiple languages: Rust, C, C++, HLSL, GLSL. The main language used in the codebase is Rust, which is used for the dashboard, networking, video decoding and audio code. C and C++ are used for graphics, video encoding and SteamVR integration. HLSL is used for graphics shaders on the Windows driver, GLSL is used on the Linux driver and the app. Moving forward, more code will be rewritten from C/C++ to Rust and HLSL code will be moved to GLSL or WGSL. Rust is a system programming language focused on memory safety and ease of use. It is as performant as C++ but Rust code is less likely to be affected by runtime bugs. The prime feature Rust feature used by ALVR is enums, that correspond to tagged unions in C++. Rust's enum is a data type that stores different kinds of data, but only one type can be accessed at a time. For example the type `Result` can contain either an `Ok` value or an `Err` value but not both. Together with pattern matching, this is the foundation of error management in Rust applications. @@ -72,19 +72,19 @@ ALVR code is hosted in a monorepo. This is an overview of the git tree: * `.github/`: Contains scripts used by the GitHub CI. * `alvr/`: Each subfolder is a Rust crate ("crate" means a code library or executable). - * `audio/`: Utility crate hosting audio related code shared by client and driver. - * `client_core/`: Platform agnostic code for the client. It is used as a Rust library for `alvr_client_openxr` and can also compiled to a C ABI shared library with a .h header for integration with other projects. - * `client_mock/`: Client mock implemented as a thin wrapper around `alvr_client_core`. - * `client_openxr/`: Client implementation using OpenXR, compiled to a APK binary. + * `audio/`: Utility crate hosting audio related code shared by app and driver. + * `client_core/`: Platform agnostic code for the app. It is used as a Rust library for `alvr_client_openxr` and can also compiled to a C ABI shared library with a .h header for integration with other projects. + * `client_mock/`: Device mock implemented as a thin wrapper around `alvr_client_core`. + * `client_openxr/`: App implementation using OpenXR, compiled to a APK binary. * `common/`: Some common code shared by other crates. It contains code for versioning, logging, struct primitives, and OpenXR paths. * `dashboard/`: The dashboard application. * `events/`: Utility crate hosting code related to events. * `filesystem/`: Utility crate hosting code for filesystem abstraction between Windows and Linux. - * `packets/`: Utility crate containing packet definitions for communication between client, driver and dashboard. + * `packets/`: Utility crate containing packet definitions for communication between device, driver and dashboard. * `server/`: The driver shared library loaded by SteamVR. * `server_io/`: Common functionality shared by dashboard and driver, for interaction with the host system. This allows dashboard and driver to work independently from each other. * `session/`: Utility crate related to session file and data management. - * `sockets/`: Utility crate shared by client and driver with socket and protocol implementation. + * `sockets/`: Utility crate shared by app and driver with socket and protocol implementation. * `vrcompositor_wrapper/`: Small script used on Linux to correctly load the ALVR Vulkan layer by SteamVR. * `vulkan_layer/`: Vulkan WSI layer used on Linux to work around limitations of the OpenVR API on Linux. This is mostly patchwork and hopefully will be removed in the future. * `xtask/`: Utility CLI hosting a variety of scripts for environment setting, building, and packaging ALVR. Should be called with `cargo xtask`. @@ -144,7 +144,7 @@ Log is a special kind of event: The driver logs events in JSON form to `session.json`, one per line. -Currently its use is limited, but eventually this will replace the current logging system, and logging will be built on top of the event system. The goal is to create a unified star-shaped network where each client and dashboard instance sends events to the server and the server broadcasts events to all other clients and dashboard instances. This should also unify the way the server communicates with clients and dashboards, making the dashboard just another client. +Currently its use is limited, but eventually this will replace the current logging system, and logging will be built on top of the event system. The goal is to create a unified star-shaped network where each device and dashboard instance sends events to the server and the server broadcasts events to all other devices and dashboard instances. This should also unify the way the server communicates with devices and dashboards, making the dashboard just another client. ## Session and settings @@ -153,7 +153,7 @@ ALVR uses a unified configuration file, that is `session.json`. It is generated * `"server_version"`: the current version of the streamer. It helps during a version upgrade. * `"drivers_backup"`: temporary storage for SteamVR driver paths. Used by the dashboard. * `"openvr_config"`: contains a list of settings that have been checked for a diff. It is used by C++ code inside the driver. -* `"client_connections"`: contains entries corresponding to known clients. +* `"client_connections"`: contains entries corresponding to known devices. * `"session_settings"`: all ALVR settings, laid in a tree structure. ### Procedural generation of code and UI @@ -183,7 +183,7 @@ These are the main components: TODO: Add screenshots * Sidebar: is used to select the tab for the main content page. -* Devices tab: used to trust clients or add them manually specifying the IP +* Devices tab: used to trust devices or add them manually specifying the IP * Statistics tab: shows graphs for latency and FPS and a summary page * Settings tab: settings page split between `Presets` and `All Settings`. `All Settings` are procedurally generated from a schema. `Presets` are controls that modify other settings. * Installation tab: utilities for installation: setting firewall rules, registering the driver, launching the setup wizard. @@ -201,7 +201,7 @@ The dashboard communicates with the driver in order to update its information an * `/api/events`: This endpoint is upgraded to a websocket and is used for listening to events from the driver * `/api/ping`: returns code 200 when the driver is alive. -The dashboard retains some functionality when the driver is not launched. It can manage settings, clients and perform installation actions, but clients cannot be discovered. Once The driver is launched all these actions are performed by the server, requested with the HTTP API. This mechanism ensures that there are no data races. +The dashboard retains some functionality when the driver is not launched. It can manage settings, devices and perform installation actions, but devices cannot be discovered. Once The driver is launched all these actions are performed by the server, requested with the HTTP API. This mechanism ensures that there are no data races. ### Driver lifecycle @@ -229,26 +229,26 @@ This might seem unnecessarily complicated. The reason for the first message roun The goal of ALVR is to bridge input and output of a PCVR application to a remote headset. In order to do this ALVR implements pipelines to handle input, video and audio. The tracking-video pipeline (as known as the motion-to-photon pipeline) is the most complex one and it can be summarized in the following steps: -* Poll tracking data on the client +* Poll tracking data on the device * Send tracking to the driver * Execute the PCVR game logic and render layers * Compose layers into a frame * Encode the video frame -* Send the encoded video frame to the client through the network -* Decode the video frame on the client +* Send the encoded video frame to the device through the network +* Decode the video frame on the device * Perform more compositor transformations * Submit the frame to the VR runtime * The runtime renders the frame during a vsync. -## Client-driver communication +## Device-driver communication -ALVR uses a custom protocol for client-driver communication. ALVR supports UDP and TCP transports. USB connection is supported although not as a first class feature; you can read more about it [here](https://github.com/alvr-org/ALVR/wiki/ALVR-wired-setup-(ALVR-over-USB)). +ALVR uses a custom protocol for device-driver communication. ALVR supports UDP and TCP transports. USB connection is supported although not as a first class feature; you can read more about it [here](https://github.com/alvr-org/ALVR/wiki/ALVR-wired-setup-(ALVR-over-USB)). ### Discovery -Usually the first step to establish a connection is discovery. When the server discovers a client it shows it in the "New devices" section in the Devices tab. The user can then trust the client and the connection is established. +Usually the first step to establish a connection is discovery. When the server discovers a device it shows it in the "New devices" section in the Devices tab. The user can then trust the device and the connection is established. -ALVR uses a UDP socket at 9943 for discovery. The client broadcasts a packet and waits for the driver to respond. It's the client that broadcasts and it's the driver that then asks for a connection: this is because of the balance in responsibility of the two peers. The client becomes the portal though a PC, that can contain sensitive data. For this reason the server has to trust the client before initiating the connection. +ALVR uses a UDP socket at 9943 for discovery. The device app broadcasts a packet and waits for the driver to respond. It's the device that broadcasts and it's the driver that then asks for a connection: this is because of the balance in responsibility of the two peers. The device becomes the portal to a PC, that can contain sensitive data. For this reason the server has to trust the device before initiating the connection. This is the layout of the discovery packet @@ -256,9 +256,9 @@ This is the layout of the discovery packet | :---------------: | :---------: | :------: | | "ALVR" + 0x0 x 12 | 8 bytes | 32 bytes | -* The prefix is used to filter packets and ensure a packet is really sent by an ALVR client -* The protocol ID is a unique version identifier calculated from the semver version of the client. If the client version is *semver-compatible* with the streamer, the protocol ID will match. -* Hostname: the hostname is a unique identifier for a client. When a client is launched for the first time, an hostname is chosen and it persists for then successive launches. It is reset when the app is upgraded or downgraded. +* The prefix is used to filter packets and ensure a packet is really sent by an ALVR device +* The protocol ID is a unique version identifier calculated from the semver version of the app. If the app version is *semver-compatible* with the streamer, the protocol ID will match. +* Hostname: the hostname is a unique identifier for a device. When a device is launched for the first time, an hostname is chosen and it persists for then successive launches. It is reset when the app is upgraded or downgraded. The format of the packet can change between major versions, but the prefix must remain unchanged, and the protocol ID must be 8 bytes. @@ -266,13 +266,13 @@ The format of the packet can change between major versions, but the prefix must ALVR uses two sockets for streaming: the control socket and stream socket. Currently these are implemented with async code; there's a plan to move this back to sync code. -The control socket uses the TCP transport; it is used to exchange small messages between client and server, ALVR requires TCP to ensure reliability. +The control socket uses the TCP transport; it is used to exchange small messages between device and server, ALVR requires TCP to ensure reliability. The stream socket can use UDP or TCP; it is used to send large packets and/or packets that do not require reliability, ALVR is robust to packet losses and packet reordering. The specific packet format used over the network is not clearly defined since ALVR uses multiple abstraction layers to manipulate the data (bincode, tokio Length Delimited Coding). Furthermore, packets are broken up into shards to ensure they can support the MTU when using UDP. -Since the amount of data streamed is large, the socket buffer size is increased both on the driver side and on the client. +Since the amount of data streamed is large, the socket buffer size is increased both on the driver side and on the device. ## SteamVR driver @@ -280,17 +280,17 @@ The driver is the component responsible for most of the streamer functionality. Using the OpenVR API, ALVR pushes tracking and button data to SteamVR using `vr::VRServerDriverHost()->TrackedDevicePoseUpdated()`. SteamVR then returns a rendered game frame with associated pose used for rendering. On Windows, frames are retrieved implementing the `IVRDriverDirectModeComponent` interface: SteamVR calls `IVRDriverDirectModeComponent::Present()`. On Linux this API doesn't work, and so ALVR uses a WSI Vulkan layer to intercept display driver calls done by vrcompositor. The pose associated to the frame is obtained from the vrcompositor execution stack with the help of libunwind. -## Client and driver compositors +## Device and driver compositors ALVR is essentially a bridge between PC and headset that transmits tracking, audio and video. But it also implements some additional features to improve image quality and streaming performance. To this goal, ALVR implements Fixed Foveated Rendering (FFR) and color correction. -The client compositor is implemented in OpenGL, while on the server it's either implemented with DirectX 11 on Windows or Vulkan on Linux. There are plans to move all compositor code to the graphics abstraction layer [wgpu](https://github.com/gfx-rs/wgpu), mainly for unifying the codebase. +The app compositor is implemented in OpenGL, while on the server it's either implemented with DirectX 11 on Windows or Vulkan on Linux. There are plans to move all compositor code to the graphics abstraction layer [wgpu](https://github.com/gfx-rs/wgpu), mainly for unifying the codebase. It's important to note that ALVR's compositors are separate from the headset runtime compositor and SteamVR compositors. The headset runtime compositor is part of the headset operative system and controls compositing between different apps and overlays, and prepares the image for display (with lens distortion correction, chroma aberration correction, mura and ghosting correction). On the driver side, on Windows ALVR takes responsibility for compositing layers returned by SteamVR. The only responsibility of SteamVR is converting the frame into a valid DXGI texture if the game uses OpenGL or Vulkan graphics. On Linux ALVR grabs Vulkan frames that are already composited by vrcompostor. This introduced additional challenges since vrcompositor implements async reprojection which disrupts our head tracking mechanism. ### Foveated encoding -Foveated rendering is a technique where frame images are individually compressed in a way that the human eye barely detects the compression. Particularly, the center of the image is kept at original resolution, and the rest is compressed. ALVR refers to foveated rendering as "Foveated encoding" to clarify its scope. In native standalone or PCVR apps, foveated rendering reduces the load on the GPU by rendering parts of the image ar lower resolution. In ALVR's case frames are still rendered at full resolution, but are then "encoded" (compressing the outskirts of the image) before actually encoding and transmitting them. The image is then reexpanded on the client side after decoding and before display. +Foveated rendering is a technique where frame images are individually compressed in a way that the human eye barely detects the compression. Particularly, the center of the image is kept at original resolution, and the rest is compressed. ALVR refers to foveated rendering as "Foveated encoding" to clarify its scope. In native standalone or PCVR apps, foveated rendering reduces the load on the GPU by rendering parts of the image ar lower resolution. In ALVR's case frames are still rendered at full resolution, but are then "encoded" (compressing the outskirts of the image) before actually encoding and transmitting them. The image is then reexpanded on the device side after decoding and before display. Currently ALVR supports only fixed foveation, but support for tracked eye foveation is planned. @@ -302,15 +302,15 @@ Color correction is implemented on the server and adds simple brightness, contra ## Video transcoding -To be able to send frames from driver to client through the network, they have to be compressed since current WiFi technology doesn't allow to send the amount of data of raw frames. Doing a quick conservative calculation, let's say we have 2 x 2048x2048 eye images, 3 color channels, 8 bits per channel, sent 72 times per second, that would amount to almost 15 Gbps. +To be able to send frames from driver to the device through the network, they have to be compressed since current WiFi technology doesn't allow to send the amount of data of raw frames. Doing a quick conservative calculation, let's say we have 2 x 2048x2048 eye images, 3 color channels, 8 bits per channel, sent 72 times per second, that would amount to almost 15 Gbps. -ALVR uses h264 and HEVC video codecs for compression. These codecs are chosen since they have hardware decoding support on Android and generally hardware encoding support on the PC side. On Windows, the driver uses NvEnc for Nvidia GPUs and AMF for AMD GPUS; on Linux ALVR supports VAAPI, NvEnc and AMF through FFmpeg. In case the GPU doesn't support hardware encoding, on both Windows and Linux ALVR supports software encoding with x264 (through FFmpeg), although the performance is often insufficient for a smooth experience. The client supports only MediaCodec, which is the API to access hardware video codecs on Android. +ALVR uses h264 and HEVC video codecs for compression. These codecs are chosen since they have hardware decoding support on Android and generally hardware encoding support on the PC side. On Windows, the driver uses NvEnc for Nvidia GPUs and AMF for AMD GPUS; on Linux ALVR supports VAAPI, NvEnc and AMF through FFmpeg. In case the GPU doesn't support hardware encoding, on both Windows and Linux ALVR supports software encoding with x264 (through FFmpeg), although the performance is often insufficient for a smooth experience. The app supports only MediaCodec, which is the API to access hardware video codecs on Android. h264 and HEVC codecs compression works on the assumption that consecutive frames are similar to each other. Each frame is reconstructed from past frames + some small additional data. For this reason, packet losses may cause glitches that persist many frames after the missing frame. When ALVR detects packet losses, it requests a new IDR frame from the encoder. A IDR frame is a packet that contains all the information to build a whole frame by itself; the encoder will ensure that successive frames will not rely on older frames than the last requested IDR. ## Audio -Game audio is captured on the PC and sent to the client, and microphone audio is captured on the client and sent to the PC. Windows and Linux implementation once again differ. On Windows, game audio is captured from a loopback device; microphone is is sent to virtual audio cable software to expose audio data from a (virtual) input device. On Linux the microphone does not work out-of-the-box, but there is a bash script available for creating and plugging into pipewire audio devices. +Game audio is captured on the PC and sent to the device, and microphone audio is captured on the device and sent to the PC. Windows and Linux implementation once again differ. On Windows, game audio is captured from a loopback device; microphone is is sent to virtual audio cable software to expose audio data from a (virtual) input device. On Linux the microphone does not work out-of-the-box, but there is a bash script available for creating and plugging into pipewire audio devices. Unlike for video, audio is sent as a raw PCM waveform and new packets do not rely on old packets. But packet losses may still cause popping, which happens when there is a sudden jump in the waveform. To mitigate this, when ALVR detects a packet loss (or a buffer overflow or underflow) it will render a fadeout or cross-fade. @@ -326,7 +326,7 @@ On the streamer side, ALVR needs to workaround a OpenVR API limitation. SteamVR ## Other streams -There are some other kinds of data which can be streamed without requiring any special timing. These are button presses and haptics, respectively sent from client to driver and from driver to client. +There are some other kinds of data which can be streamed without requiring any special timing. These are button presses and haptics, respectively sent from the device to the driver and from the driver to the device. ## Upcoming @@ -336,7 +336,7 @@ Phase sync is not a single algorithm but many that share similar objectives, red In general, a phase sync algorithm is composed of two parts: a queue that holds data resources or pointers, and a statistical model to predict event times. The statistical model is fed with duration or other kinds of timing samples and as output it returns a refined time prediction for a recurring event. The statistical model could be simple and just aim for a average-controlled event, or more complex that aims for submitting for a deadline; the second case needs to take into account the variance of the timing samples. Unlike Oculus implementation, these statistical models can be highly configurable to tune the target mean or target variance. -There are a few phase sync algorithms planned to be implemented: frame submission timing (to reduce frame queueing on the client, controlled by shifting the phase of the driver rendering cycle), SteamVR tracking submission timing (to make sure SteamVR is using exactly the tracking sample we want) and tracking poll timing (to reduce queuing on the server side). +There are a few phase sync algorithms planned to be implemented: frame submission timing (to reduce frame queueing on the headset, controlled by shifting the phase of the driver rendering cycle), SteamVR tracking submission timing (to make sure SteamVR is using exactly the tracking sample we want) and tracking poll timing (to reduce queuing on the server side). ## Sliced encoding diff --git a/wiki/Installation-guide.md b/wiki/Installation-guide.md index abc6ce5982..3b5b577115 100644 --- a/wiki/Installation-guide.md +++ b/wiki/Installation-guide.md @@ -2,7 +2,7 @@ ## Launcher (BETA) -Launcher will allow you to manage old, current and new installations of ALVR streamer and allow to automatically install and upgrade to specific ALVR client version on headset +Launcher will allow you to manage old, current and new installations of ALVR streamer and allow to automatically install and upgrade to specific ALVR app version on headset ### Installation @@ -11,13 +11,13 @@ Launcher will allow you to manage old, current and new installations of ALVR str * Press `Add version` button * For default installation keep channel and version as is and press `Install` * Wait until it finishes downloading, installing (depends on your connection) -* To install ALVR client on headset, use button `Install APK` +* To install ALVR app on headset, use button `Install APK` * In the list, to open streamer app (PC) press `Launch`. You will be greeted with a setup wizard. Follow the setup to set the firewall rules and other settings. ### Usage * Before launching SteamVR through ALVR, please install it. First time launch will result in steamvr being blank and alvr will not work - close it and start again. It will have registered driver and should work. -* Launch ALVR client on your headset. While the headset screen is on, click `Trust` next to the client entry (in the ALVR streamer app on PC, in the `Devices` tab) to start streaming. +* Launch ALVR app on your headset. While the headset screen is on, click `Trust` next to the device entry (in the ALVR streamer app on PC, in the `Devices` tab) to start streaming. * You can change settings on the PC in the `Settings` tab. Most of the settings require to restart SteamVR to be applied. Use the apposite button on the bottom right corner. For any problem visit the [Troubleshooting page](https://github.com/alvr-org/ALVR/wiki/Troubleshooting). @@ -30,7 +30,7 @@ Then you can enable the microphone in the ALVR setting, leave "Virtual microphon ## Advanced installation -### Installing client using Sidequest +### Installing app using Sidequest * Install SideQuest on your PC and enable developer mode on the headset. You can follow [this guide](https://sidequestvr.com/setup-howto). * Connect your headset to Sidequest. If you have Quest, Pico, and other compatible device download the ALVR app [here](https://sidequestvr.com/app/9) diff --git a/wiki/Linux-Troubleshooting.md b/wiki/Linux-Troubleshooting.md index 74bbb2c727..8dedd8d0cd 100644 --- a/wiki/Linux-Troubleshooting.md +++ b/wiki/Linux-Troubleshooting.md @@ -3,7 +3,7 @@ ## SteamVR The steam runtimes SteamVR runs in break the alvr driver loaded by SteamVR. -This causes the screen to stay black on the client or an error to be reported that the pipewire device is missing or can even result in SteamVR crashing. +This causes the screen to stay black on the headset or an error to be reported that the pipewire device is missing or can even result in SteamVR crashing. ### Fix @@ -84,4 +84,4 @@ This might be caused by [[PERF] Subpar GPU performance due to wrong power profil ### Fix -Using CoreCtrl is highly advised (install it using your distribution package management) and in settings set your GPU to VR profile, as well as cpu to performance profile (if it's old Ryzen cpu). \ No newline at end of file +Using CoreCtrl is highly advised (install it using your distribution package management) and in settings set your GPU to VR profile, as well as cpu to performance profile (if it's old Ryzen cpu). diff --git a/wiki/Settings-tutorial.md b/wiki/Settings-tutorial.md index 9bdf82b3d7..617d95c5b0 100644 --- a/wiki/Settings-tutorial.md +++ b/wiki/Settings-tutorial.md @@ -7,7 +7,7 @@ as well as give you some pointers to troubleshoot common configuration issues. ## Prerequisites -* You have installed the ALVR streamer on your PC, and the ALVR client on your HMD. +* You have installed the ALVR streamer on your PC, and the ALVR app on your HMD. * You can launch up to the SteamVR void (or up to the SteamVR home) and are able to launch games. ## Step 1: choose resolution, refresh rate, codec @@ -42,7 +42,7 @@ Slowly increase bitrate until one of two things happen: ## Step 4: tweak frame buffering -If you notice micro-stuttering in the client, especially in busy scenes with fast motion, slowly increase maxBufferingFrames until the playback is smooth. +If you notice micro-stuttering on the headset, especially in busy scenes with fast motion, slowly increase maxBufferingFrames until the playback is smooth. Keep in mind that increasing maxBufferingFrames will linearly increase latency; if the value that gives a smooth playback results in too high of a latency for diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md index 62c6b5410f..b7cbc561eb 100644 --- a/wiki/Troubleshooting.md +++ b/wiki/Troubleshooting.md @@ -78,14 +78,14 @@ ALVR on the headset stuck on `Searching for streamer...` This issue can have multiple causes. It is likely that the issue is with the PC ALVR application. See below for more specific issues. -ALVR client list is empty +ALVR device list is empty --- -![Empty ALVR client list](images/ALVRexe-no-clients.png) +![Empty ALVR device list](images/ALVRexe-no-clients.png) Check that the PC app and the headset app run on the latest version of ALVR. If your version is v2.3.1 or v2.4.0-alpha5 then you downloaded ALVR from the wrong link. The correct link is . -Make sure ALVR is running both on the PC and on the headset. To be visible in the client list, ALVR on the headset sends broadcast packets which the PC application listens for. These can be blocked by your firewall or possibly your router, if both headset and PC are connected wirelessly, having AP isolation enabled on the router will cause this. +Make sure ALVR is running both on the PC and on the headset. To be visible in the device list, ALVR on the headset sends broadcast packets which the PC application listens for. These can be blocked by your firewall or possibly your router, if both headset and PC are connected wirelessly, having AP isolation enabled on the router will cause this. To fix this, you can try the following: @@ -94,7 +94,7 @@ To fix this, you can try the following: * Open ports 9943 and 9944 on your firewall * Disable the PMF (Protected Management Frames) setting on your Router -If pinging works but you still don't see the client on the streamer app, then headset and PC might be on separate subnets. To solve this you can add the client manually. +If pinging works but you still don't see the device on the streamer app, then headset and PC might be on separate subnets. To solve this you can add the device manually. In the Devices tab press `Add device manually`. Fill in the fields with a name for your headset (you can use the name you want), the hostname (you can read it in the welcome screen in your headset when you open the ALVR app), the IP of the headset and then press `Save`. SteamVR says "headset not detected" @@ -127,7 +127,7 @@ ALVR sees the headset, SteamVR shows headset icon ![SteamVR waiting...](images/SteamVR-waiting.png) -This is a situation where you have ALVR open on both headset and PC, you can see the headset in the client list and trust it. ALVR then starts SteamVR automatically when you try connecting and SteamVR shows an icon for the headset (and controllers). +This is a situation where you have ALVR open on both headset and PC, you can see the headset in the device list and trust it. ALVR then starts SteamVR automatically when you try connecting and SteamVR shows an icon for the headset (and controllers). First make sure that SteamVR (more specifically, vrserver.exe) is allowed incoming connections (UDP, port 9944) in your firewall. You can also try disabling your firewall for testing, but you keep it disabled to use ALVR. @@ -139,7 +139,7 @@ You can try restarting ALVR on both the headset and the PC. On the headset, when ![latency graph of overloaded encoder](images/latency-graphs/overloaded-encoder.png) -Symptoms: stuttery playback in the client, streamer FPS is stable but below the target refresh rate. +Symptoms: stuttery playback on the headset, streamer FPS is stable but below the target refresh rate. Solution: increase foveation settings or decrease refresh rate. @@ -163,7 +163,7 @@ Solution: check that HMD is using 5G frequency and that no other device is conne ![latency graph of overloaded streamer](images/latency-graphs/overloaded-streamer.png) -Symptoms: stuttery playback in the client, streamer FPS dips or fluctuates below the target refresh rate. +Symptoms: stuttery playback on the headset, streamer FPS dips or fluctuates below the target refresh rate. Solution: @@ -174,7 +174,7 @@ Solution: ### Micro-stuttering -![latency graph of client stuttering](images/latency-graphs/not-enough-buffering.png) +![latency graph of headset stuttering](images/latency-graphs/not-enough-buffering.png) Symptoms: image is not always smooth especially in high motion or fast scenes. diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index ad1e563c17..35ecdcd700 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -14,7 +14,7 @@ * [Information and Recommendations](https://github.com/alvr-org/ALVR/wiki/Information-and-Recommendations) -* [ALVR client and streamer on separate networks](https://github.com/alvr-org/ALVR/wiki/ALVR-client-and-streamer-on-separate-networks) +* [ALVR headset and streamer on separate networks](https://github.com/alvr-org/ALVR/wiki/ALVR-client-and-streamer-on-separate-networks) * [Fixed Foveated Rendering (FFR)](https://github.com/alvr-org/ALVR/wiki/Fixed-Foveated-Rendering-(FFR))