sam_oneal/fx_cast
1
0
Fork 0
mirror of https://github.com/hensm/fx_cast.git synced 2026-06-08 08:39:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
hensm
2022-04-21 14:14:19 +01:00
parent 2f2792187c
commit 241080d041
1 changed files with 119 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

223
README.md
View File

@@ -5,30 +5,40 @@
# fx_cast # fx_cast
Firefox extension that implements the [Chrome sender API](https://developers.google.com/cast/docs/reference/chrome/) and exposes it to web apps to enable cast support. Communication with receiver devices is handled by a native application (bridge). Check the [implementation notes](IMPLEMENTATION.md) for more info. A Firefox extension that implements the Chromecast API and exposes it to web apps to enable cast support. Communication with receiver devices is handled by a companion application (bridge).
_**Note**: No full public release yet! Pre-release beta version is incomplete and likely buggy._
## Installing ## Installing
_**Note**: Currently supported on macOS, Windows and Linux._ Install the Firefox extension (from within Firefox) and bridge application via the installer packages. These are two separate downloads that can be found on the [website](https://hensm.github.io/fx_cast/) or in the [GitHub releases](https://github.com/hensm/fx_cast/releases) section.
Install the Firefox extension (from within Firefox) and companion bridge application via the installer packages. These are two separate downloads that can be found on the [website](https://hensm.github.io/fx_cast/) or in the [GitHub releases](https://github.com/hensm/fx_cast/releases) section. The bridge application is currently supported on Windows, macOS and Linux.
On Linux platforms, it may be necessary to [configure local hostname resolution](https://wiki.archlinux.org/index.php/avahi#Hostname_resolution). **Important**: On Linux platforms such as Arch, it may be necessary to [configure local hostname resolution](https://wiki.archlinux.org/index.php/avahi#Hostname_resolution)[^arch].
### Installing as a systemd deamon ### Installing via package managers
1. Create fx_cast user: `sudo useradd --system fx_cast` **Note**: These packages are maintained by third parties and support likely will not be provided for any issues specific to these packages.
2. Create service file in /etc/systemd/fx_cast.service:
- **Arch Linux (AUR)**
- `fx_cast` — https://aur.archlinux.org/packages/fx_cast
- `fx_cast-bin` — https://aur.archlinux.org/packages/fx_cast-bin
### Daemon Configuration
<details>
<summary>Daemon configuration (systemd)</summary>
1. Create `fx_cast` user:
```sh
$ sudo useradd --system fx_cast
```
2. Create service file in `/etc/systemd/fx_cast.service`:
``` ```
[Unit] [Unit]
Description=fx_cast daemon Description=fx_cast daemon
[Service] [Service]
User=fx_cast User=fx_cast
ExecStart=/opt/fx_cast/fx_cast_bridge -d ExecStart=/opt/fx_cast/fx_cast_bridge -d
Restart=always Restart=always
@@ -36,26 +46,25 @@ Restart=always
[Install] [Install]
WantedBy=multi-user.target WantedBy=multi-user.target
``` ```
3. Enable the service: `sudo systemctl enable --now fx_cast` 3. Enable the service:
```sh
### Package managers $ sudo systemctl enable --now fx_cast`
* #### Arch Linux (AUR) - https://aur.archlinux.org/packages/fx_cast/ ```
````sh </details>
yay -S fx_cast
````
## Usage ## Usage
Most websites won't load the cast API unless the browser presents itself as Chrome. The extension includes a whitelist for sites that should be given a Chrome-compatible user agent string. Whitelist entries are specified as [match patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). To whitelist all sites, add `<all_urls>` to the whitelist, though this is not recommended and could cause breakage on random sites. Clicking on the toolbar button or `Cast...` menu item in the page context menu will open a popup that shows a list of receiver devices will allow you to start casting the currently detected app[^cast_app] or media.
### Site Whitelist
The extension provides a whitelist for ensuring only trusted sites are allowed to load the cast API and communicate with receiver devices.
Sites may be added to the whitelist, either by clicking one of the whitelist options in the toolbar button context menu whilst visiting the site, or by manually entering a valid [match pattern](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) on the options page.
Whitelisted sites should then display a cast button as in Chrome, provided they're compatible with the extension/Firefox. Whitelisted sites should then display a cast button as in Chrome, provided they're compatible with the extension/Firefox.
The `Cast...` menu item is visible in the page, toolbar button and tools menus, and provides access to the receiver selector at any time to stop an existing session or start screen mirroring or file casting.
HTML5 media elements also have a different `Cast...` context menu item that triggers the media sender, though this won't work for media using EME/MSE.
## Building ## Building
### Requirements ### Requirements
@@ -63,7 +72,7 @@ HTML5 media elements also have a different `Cast...` context menu item that trig
* Native build tools (see [here](https://github.com/nodejs/node-gyp#installation)) * Native build tools (see [here](https://github.com/nodejs/node-gyp#installation))
* Bonjour/Avahi (on Windows/Linux respectively) * Bonjour/Avahi (on Windows/Linux respectively)
Cross-compiling native depedencies may be possible, but isn't tested or supported. Build script options are provided for building/packaging on other platforms, but assume they won't work. Packaging on Linux for other Linux package formats should work fine. Cross-compiling native dependencies may be possible, but isn't tested or supported. Build script options are provided for building/packaging on other platforms, but assume they won't work. Packaging on Linux for other Linux package formats should work fine.
### Installing dependencies ### Installing dependencies
@@ -73,119 +82,119 @@ Cross-compiling native depedencies may be possible, but isn't tested or supporte
#### Debian / Ubuntu: #### Debian / Ubuntu:
````sh ````sh
sudo apt install libavahi-compat-libdnssd-dev dpkg rpm $ sudo apt install libavahi-compat-libdnssd-dev dpkg rpm
# Runtime: avahi-daemon
```` ````
Runtime packages: `avahi-daemon`.
#### Fedora: #### Fedora:
````sh ````sh
sudo dnf install avahi-compat-libdns_sd-devel dpkg rpm-build $ sudo dnf install avahi-compat-libdns_sd-devel dpkg rpm-build
# Runtime: avahi nss-mdns
```` ````
Runtime packages: `avahi`, `nss-mdns`.
#### Arch Linux: #### Arch Linux:
````sh ````sh
sudo pacman -S avahi dpkg $ sudo pacman -S avahi dpkg rpm-tools
yay -S rpm-org
```` ````
### Instructions ### Instructions
````sh ````sh
git clone https://github.com/hensm/fx_cast.git $ git clone https://github.com/hensm/fx_cast.git
cd fx_cast $ cd fx_cast
npm install $ npm install
npm run build $ npm run build
# Install manifest for dist/ build. Installs to # Install manifest for dist/ build. Installs to
# user-specific location and overrides a system-wide # user-specific location and overrides a system-wide
# install. Call `remove-manifest` to restore previous state. # install. Call `remove-manifest` to restore previous state.
npm run install-manifest $ npm run install-manifest
npm run remove-manifest $ npm run remove-manifest
```` ````
This will build the ext and app, outputting to `dist/`: This will build the ext and app, outputting to `dist/`:
* #### `dist/app/` - `dist/app/`
... contains the built bridge with launcher script and manifest with the path pointing that script. The `install-manifest` script copies this manifest to the proper location (or adds its current location to the registry on Windows). ... contains the built bridge with launcher script and manifest (with the path pointing that script). The `install-manifest` npm script copies this manifest to the proper location (or adds its current location to the registry on Windows).
* #### `dist/ext/` - `dist/ext/`
... contains the unpacked extension. ... contains the unpacked extension.
Watching ext changes: Watching ext changes:
````sh ````sh
npm run watch --prefix ./ext $ npm run watch --prefix ./ext
```` ````
Launch Firefox with built extension (run in separate terminal): Launch Firefox with built extension (run in separate terminal):
````sh ````sh
npm run start --prefix ./ext $ npm run start --prefix ./ext
```` ````
#### Extension build script arguments
* `--package`
Should package with web-ext.
* `--watch`
Should run webpack in watch mode.
* `--mirroringAppId` `"<appID>"`
Provide an alternative default mirroring receiver app ID.
* `--mode` `"production"`, `"development"`
Run webpack in a different mode. Defaults to `"development"` unless combined with `--package`.
#### Bridge build script arguments
* `--usePkg`
Creates a single executable instead of a launcher script.
* `--package`
Builds and creates installer packages for distribution.
* `--arch` `"x64"`,`"x86"`
Select platform arch to build for. Defaults to current platform arch.
* `--skipNativeBuilds`
macOS only. Skips native receiver selector build.
#### 32-bit on Windows #### 32-bit on Windows
Building a 32-bit version is only supported for Windows. If you're building from a 64-bit system, you'll also need to rebuild any native dependencies as 32-bit. Building a 32-bit version is only supported for Windows. If you're building from a 64-bit system, you'll also need to rebuild any native dependencies as 32-bit.
````sh ````sh
npm clean-install --prefix ./app --arch=ia32 # If on a 64-bit system $ npm clean-install --prefix ./app --arch=ia32 # If on a 64-bit system
npm run build:app -- -- --arch=x86 --usePkg # If building without packaging # If building without packaging
npm run package:app -- -- --arch=x86 # ... else if packaging $ npm run build:app -- -- --arch=x86 --usePkg
# If packaging
$ npm run package:app -- -- --arch=x86
```` ````
### Build scripts
Extension build script (`build:ext`) arguments:
- `--package`
Should package with web-ext.
- `--watch`
Should run webpack in watch mode.
- `--mirroringAppId` `"<appID>"`
Provide an alternative default mirroring receiver app ID.
- `--mode` `"production"`, `"development"`
Run webpack in a different mode. Defaults to `"development"` unless combined with `--package`.
Bridge build script (`build:app`) arguments:
- `--usePkg`
Creates a single executable instead of a compiled JavaScript files and a launcher script.
- `--package`
Builds and creates installer packages for distribution.
- `--arch` `"x64"`,`"x86"`
Select platform arch to build for. Defaults to current platform arch.
### Packaging ### Packaging
Build and package extension and bridge application for current platform: Build and package extension and bridge application for current platform:
````sh ```sh
npm run package $ npm run package
```` ```
* #### `dist/app/` - `dist/app/`
... contains the installer package: `fx_cast_bridge-<version>-<arch>.(pkg|deb|rpm|exe)` ... contains the installer package: `fx_cast_bridge-<version>-<arch>.(pkg|deb|rpm|exe)`
* #### `dist/ext/` - `dist/ext/`
... contains the built extension archive: `fx_cast-<version>.xpi`. ... contains the built extension archive: `fx_cast-<version>.xpi`.
Packaging examples: Packaging examples:
````sh ```sh
npm run package:ext # Packaging extension $ npm run package:ext # Packaging extension
npm run package:app # Packaging bridge application $ npm run package:app # Packaging bridge application
# Linux platforms # Linux platforms
npm run package:app -- -- --packageType=deb $ npm run package:app -- -- --packageType=deb
npm run package:app -- -- --packageType=rpm $ npm run package:app -- -- --packageType=rpm
```` ```
#### Bridge package script arguments #### Bridge package script arguments
_**Note**: Includes the build script arguments._ _**Note**: Includes the build script arguments._
* `--packageType` `"deb"`,`"rpm"` - `--packageType` `"deb"`,`"rpm"`
Select the package type. Defaults to `deb`. Only relevant when building for Linux. Select the package type. Defaults to `deb`. Only relevant when building for Linux.
@@ -193,42 +202,48 @@ _**Note**: Includes the build script arguments._
Testing requires geckodriver (or chromedriver for Chrome parity testing). See [selenium-webdriver](https://www.npmjs.com/package/selenium-webdriver#installation) installation instructions (ignore `npm install`). Testing requires geckodriver (or chromedriver for Chrome parity testing). See [selenium-webdriver](https://www.npmjs.com/package/selenium-webdriver#installation) installation instructions (ignore `npm install`).
The test script expects a compatible installed bridge version and an extension archive at `dist/ext/`. The test script expects a compatible installed bridge version and a packaged extension archive at `dist/ext/`.
Test results will be displayed in the terminal and within the opened browser tab. Chrome may take some time to initialize the media router component before the cast API is available for testing. Test results will be displayed in the terminal and within the opened browser tab. Chrome may take some time to initialize the media router component before the cast API is available for testing.
````sh ```sh
npm run build --prefix ./app $ npm run build --prefix ./app
npm run install-manifest $ npm run install-manifest
npm run package --prefix ./ext $ npm run package --prefix ./ext
npm test $ npm test
SELENIUM_BROWSER=chrome npm test
```` # Or if testing in Chrome
$ SELENIUM_BROWSER=chrome npm test
```
## Video Demos ## Video Demos
Netflix / HTML5: These are somewhat outdated now, but show the basic function of the extension:
[<img width="200" src="https://img.youtube.com/vi/Ex9dWKYguEE/0.jpg" alt="fx_cast Netflix" />](https://www.youtube.com/watch?v=Ex9dWKYguEE) [<img width="200" src="https://img.youtube.com/vi/Ex9dWKYguEE/0.jpg" alt="fx_cast Netflix" />](https://www.youtube.com/watch?v=Ex9dWKYguEE)
[<img width="200" src="https://img.youtube.com/vi/16r8lQKeEX8/0.jpg" alt="fx_cast HTML5" />](https://www.youtube.com/watch?v=16r8lQKeEX8) [<img width="200" src="https://img.youtube.com/vi/16r8lQKeEX8/0.jpg" alt="fx_cast HTML5" />](https://www.youtube.com/watch?v=16r8lQKeEX8)
## Credit ## Credit
- [electron-chromecast](https://github.com/GPMDP/electron-chromecast)[^electron]
_**Note**: Since it seems to be causing confusion, this project does not use electron. The electron-chromecast library was only used as a reference for the initial implementation of the API._ - Icons by [icons8](https://icons8.com/):
- `ext/src/ui/options/assets/icons8-cancel-120.png`
* [electron-chromecast](https://github.com/GPMDP/electron-chromecast) - `ext/src/ui/options/assets/icons8-ok-120.png`
* [node-castv2](https://github.com/thibauts/node-castv2) - `ext/src/ui/options/assets/icons8-warn-120.png`
* [icons8](https://icons8.com/)
## Donation ## Donations
### PayPal ### PayPal
<p style="float: left">
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3Z2FTMSG976WN&source=url">
<img src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" alt="Donate with PayPal button" align="middle">
</a>
<img alt="Donate with PayPal" src="https://i.imgur.com/oisL6Eo.png" align="middle">
</p>
To donate via PayPal: [^arch]:
By default, Arch does not configure Avahi to resolve `.local` hostnames via the name service switch (NSS), and the underlying mdns module used by this project relies on [`getaddrinfo`](https://en.wikipedia.org/wiki/Getaddrinfo) to resolve these hostnames correctly.
[<img src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" alt="Donate with PayPal button">](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=3Z2FTMSG976WN&source=url) [^cast_app]:
Some sites may only function properly when initiating casting from the in-page player buttons.
<img alt="Donate with PayPal" src="https://i.imgur.com/oisL6Eo.png"> [^electron]:
Since it seems to be causing confusion, this project does not use electron. The electron-chromecast library was only used as a reference for the initial implementation of the API.