440 lines
21 KiB
Markdown
440 lines
21 KiB
Markdown
# Troubleshooting
|
|
|
|
## Highlighted Issues
|
|
|
|
### Legacy dashboard resource detected
|
|
|
|
You still have the old `frigate-hass-card.js` resource registered in your
|
|
dashboard (and not `advanced-camera-card.js`). Having both registered causes
|
|
duplicate element registration errors and unpredictable behavior. Symptoms
|
|
include the card not loading, the version changing between reloads, or log
|
|
entries like:
|
|
|
|
`Failed to execute 'define' on 'CustomElementRegistry': the name "focus-trap" has already been used with this registry window`
|
|
|
|
To fix:
|
|
|
|
1. Edit your dashboard (click the three-dot menu in the top right) and select
|
|
**Manage Resources**.
|
|
1. Remove any entry referring to `frigate-hass-card`. You should only have a
|
|
single entry for `advanced-camera-card`.
|
|
1. Optionally, delete the `frigate-hass-card` directory on your filesystem if
|
|
present (e.g. `$HA_PATH/www/community/frigate-hass-card`), as long as an
|
|
`advanced-camera-card` directory exists there too.
|
|
1. Clear your browser cache and reload.
|
|
|
|
If you are an admin user and the card detects both resources are registered, an
|
|
alert icon will appear in the status bar -- clicking it will display a
|
|
notification with a button to automatically remove the legacy resource.
|
|
|
|
### Configuration upgrade available
|
|
|
|
If you see a notification that a configuration upgrade is available, it means
|
|
your card configuration uses an older format that can be automatically updated.
|
|
|
|
To upgrade:
|
|
|
|
1. Open your Home Assistant dashboard.
|
|
1. Click the pencil icon to enter edit mode.
|
|
1. Click the three-dot menu on your card and choose **Edit**.
|
|
1. In the card editor, click the **Automatic Upgrade** button at the top.
|
|
1. Review the changes and save.
|
|
|
|
If the automatic upgrade button is not visible, your configuration may already
|
|
be up to date. Try clearing your browser cache and reloading.
|
|
|
|
### Configuration could not be fully upgraded
|
|
|
|
Automatic configuration upgrades are not perfect. If you see a notification that
|
|
your configuration could not be fully upgraded, you will find part of your
|
|
configuration set aside -- untouched -- under an `__UPGRADE_FAILURE__` field.
|
|
|
|
To resolve it:
|
|
|
|
1. Edit your card's YAML manually and find the `__UPGRADE_FAILURE__` key.
|
|
1. Re-create each entry under it in the current format (see the relevant
|
|
configuration documentation in the sidebar). An upgrade usually fails this
|
|
way when a feature has been retired, or changed enough that the migration
|
|
needs human judgment.
|
|
1. Once you're happy with the result, delete the `__UPGRADE_FAILURE__` key.
|
|
|
|
The notification clears once the `__UPGRADE_FAILURE__` key is gone.
|
|
|
|
### Media unavailable
|
|
|
|
Media not loading? Permanent "loading circle"? Live view frozen?
|
|
|
|
Media failing to load is a relatively common error, but can be caused by any
|
|
number of issues (e.g. installation problems, networking problems, video/codec
|
|
problems, a Home Assistant bug or card bug). This applies to live streams,
|
|
recorded media in the viewer, and image views.
|
|
|
|
During a live stream load, the card will show a "loading circle" icon and, for
|
|
cameras with a `camera_entity` configured, will show images refreshing once per
|
|
second until the stream has fully loaded (unless `live.show_image_during_load`
|
|
is set to false).
|
|
|
|
The card attempts to recover from media playback issues. Some runtime failures
|
|
are silent: the video input simply freezes on the last frame with no error (e.g.
|
|
Frigate or camera restart, power loss, temporary network connectivity issue), so
|
|
the card watches a playing stream for a loss of new frames and treats such a
|
|
freeze as unavailable.
|
|
|
|
While media is unavailable the loading indicator returns and an alert icon
|
|
appears in the status bar. The card retries automatically with a back-off (and
|
|
the notification offers a manual retry button). A live stream additionally
|
|
reconnects on its own once its camera becomes available again.
|
|
|
|
A retry rebuilds the media from scratch, discarding the prior attempt. Media
|
|
that is merely loading slowly has not failed -- it is still loading -- so
|
|
restarting it would throw away the very attempt that may be about to succeed. A
|
|
camera reported as **Media not loading** is therefore left running for at least
|
|
30 seconds after that message appears before the card rebuilds it, unlike media
|
|
that has _actually_ failed, which is rebuilt as soon as the schedule allows. The
|
|
manual retry button rebuilds immediately regardless.
|
|
|
|
Reported reasons why media may be unavailable:
|
|
|
|
| Reason | Meaning |
|
|
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **Camera entity unavailable** | The camera's `camera_entity` reported `unavailable` in Home Assistant, e.g. the camera or its integration (such as Frigate) restarted, or the camera lost power or network. A short grace period is allowed before this is reported, and the card recovers automatically once the entity returns. Set [`always_error_if_entity_unavailable`](./configuration/cameras/README.md?id=cameras) to report it immediately instead. |
|
|
| **Media not loading** | The media did not finish loading within the expected time: a slow or failed initial load. Applies to live streams, the viewer, and image views. Nothing has necessarily failed yet, so the card keeps waiting on the existing load attempt already underway rather than restarting it immediately. |
|
|
| **Playback error** | The live provider reported an error while trying to play the stream. |
|
|
| **Stream stalled** | The stream loaded and was playing, but stopped delivering new frames with no error raised (a silent freeze). The card notices the lack of progress and reconnects. |
|
|
|
|
Debugging steps:
|
|
|
|
1. If you're using the default `auto` live provider, or explicitly setting the
|
|
`ha` live provider, try opening the `camera_entity` in Home Assistant and
|
|
verifying whether the stream loads there. You can press the `e` key on any
|
|
Home Assistant dashboard, choose the relevant entity, and see if the stream
|
|
loads. If it does not, you have an upstream installation issue with your
|
|
camera / the integration for the camera, and need to resolve that first.
|
|
Your issue is not related to the card itself.
|
|
1. Check whether any URLs specified in your card configuration are accessible
|
|
_from the network of the browser_.
|
|
1. Check whether or not there are helpful clues shown on your Javascript
|
|
console (`F12` in many browsers) that might indicate the source of the
|
|
issue.
|
|
1. Check you are using the latest version of all relevant camera integrations
|
|
(e.g.
|
|
[Frigate](https://github.com/blakeblackshear/frigate-hass-integration)).
|
|
1. If you're using a Frigate camera and are requesting a `webrtc` stream,
|
|
ensure [you have configured Frigate
|
|
accordingly](https://docs.frigate.video/configuration/live/#webrtc-extra-configuration).
|
|
1. Search for your symptoms on the [card issues
|
|
page](https://github.com/dermotduffy/advanced-camera-card/issues) and see if
|
|
you find any prior relevant discussions.
|
|
|
|
If you're happy with just using an image stream but want the small circle to go
|
|
away, use the [`image live provider`](./configuration/cameras/live-provider.md?id=image).
|
|
|
|
### Unknown Command
|
|
|
|
`Camera initialization failed: Unknown command`
|
|
|
|
Your Frigate integration may not be up to date. Check [the latest Frigate
|
|
Integration
|
|
releases](https://github.com/blakeblackshear/frigate-hass-integration/releases/tag/v5.7.0).
|
|
|
|
## Other Issues
|
|
|
|
### 2-way audio doesn't work
|
|
|
|
There are many requirements for 2-way audio to work. See [Using 2-way
|
|
audio](usage/2-way-audio.md) for more information about these. If your
|
|
microphone still does not work and you believe you meet all the requirements try
|
|
eliminating the card from the picture by going directly to the `go2rtc` UI,
|
|
navigating to `links` for your given stream, then to `webrtc.html` with a
|
|
microphone. If this does not work correctly with 2-way audio then your issue is
|
|
with `go2rtc` not with the card. In this case, you could file an issue in [that
|
|
repo](https://github.com/AlexxIT/go2rtc/issues) with debugging information as
|
|
appropriate.
|
|
|
|
### Android will not render >4 JSMPEG live views
|
|
|
|
Android Webview (as used by Android Chrome / Android Home Assistant Companion)
|
|
appears to severely limit the number of simultaneous OpenGL contexts that can be
|
|
opened. The JSMPEG player (that this card uses), consumes 1 OpenGL context per
|
|
rendering.
|
|
|
|
This limitation may be worked around (at a performance penalty) by disabling
|
|
OpenGL for JSMPEG live views:
|
|
|
|
```yaml
|
|
live:
|
|
jsmpeg:
|
|
options:
|
|
disableGl: true
|
|
```
|
|
|
|
[This bug](https://github.com/dermotduffy/advanced-camera-card/issues/191) has some
|
|
more discussion on this topic. New ideas to address this underlying limitation
|
|
most welcome!
|
|
|
|
### Autoplay in Chrome when a tab becomes visible again
|
|
|
|
Even if `live.auto_play` or `media_viewer.auto_play` is set to `[]`, Chrome
|
|
itself will still auto play a video that was previously playing prior to the tab
|
|
being hidden, once that tab is visible again. This behavior cannot be influenced
|
|
by the card. Other browsers (e.g. Firefox, Safari) do not exhibit this behavior.
|
|
|
|
### Blank white image on `live` view
|
|
|
|
For some slowly loading cameras, for which [Home Assistant stream
|
|
preloading](https://www.home-assistant.io/integrations/camera/) is not enabled,
|
|
Home Assistant may return a blank white image when asked for a still. These
|
|
stills are used during initial Advanced Camera Card load of the `live` view if the
|
|
`live.show_image_during_load` option is enabled. Disabling this option should
|
|
show the default media loading controls (e.g. a spinner or empty video player)
|
|
instead of the blank white image.
|
|
|
|
### Casting to Chromecast broken
|
|
|
|
This could be for any number of reasons. Chromecast devices can be quite picky
|
|
on network, DNS and certificate issues, as well as audio and video codecs. Check
|
|
your Home Assistant log as there may be more information in there.
|
|
|
|
> [!TIP]
|
|
> For Frigate to support casting of clips, the default ffmpeg settings for
|
|
> Frigate must be modified, i.e. Frigate does not encode clips in a Chromecast
|
|
> compatible format out of the box (specifically: audio must be enabled in the AAC
|
|
> codec, whether your camera supports audio or not). See the [Frigate Home
|
|
> Assistant documentation](https://docs.frigate.video/integrations/home-assistant/)
|
|
> or [this issue](https://github.com/blakeblackshear/frigate/issues/3175) for
|
|
> more.
|
|
|
|
### Custom element does not exist
|
|
|
|
This is usually a sign that the card is not correctly installed (i.e. the
|
|
browser cannot find the Javascript). In cases where it works in some browsers /
|
|
devices but not in others it may simply be an old browser / webview that does
|
|
not support modern Javascript (this is occasionally seen on old Android
|
|
hardware). In this latter case, you are out of luck.
|
|
|
|
### `double_tap` does not work in Android
|
|
|
|
The Android video player swallows `double_tap` interactions in order to
|
|
rewind or fast-forward. Workarounds:
|
|
|
|
- Use `hold` instead of `double_tap` for your card-wide action.
|
|
- Use an [Advanced Camera Card Element](configuration/elements/README.md) or menu icon to
|
|
trigger the action instead.
|
|
|
|
### Dragging in carousels broken in Firefox
|
|
|
|
The Firefox video player swallows mouse interactions, so dragging is not
|
|
possible in carousels that use the Firefox video player (e.g. `clips` carousel,
|
|
or live views that use the `frigate` or `webrtc-card` provider). The next and
|
|
previous buttons may be used to navigate in these instances.
|
|
|
|
Dragging works as expected for snapshots, or for the `jsmpeg` provider.
|
|
|
|
### Dragging video control doesn't work in Safari
|
|
|
|
Dragging the Safari video controls "progress bar" conflicts with carousel
|
|
"dragging", meaning the video controls progress bar cannot be moved left or
|
|
right. Turning off carousel dragging (and using next/previous controls) will
|
|
return full video controls in Safari:
|
|
|
|
```yaml
|
|
live:
|
|
draggable: false
|
|
media_viewer:
|
|
draggable: false
|
|
```
|
|
|
|
### Downloads don't work
|
|
|
|
Downloads are assembled by the Frigate backend out of ~10s segment files. You
|
|
must have enough cache space in your Frigate instance to allow this assembly to
|
|
happen -- if large downloads don't work, especially for recordings, check your
|
|
Frigate backend logs to see if it's running out of space. You can increase your
|
|
cache size with the `tmpfs` `size` argument, see [Frigate
|
|
documentation](https://docs.frigate.video/frigate/installation#docker).
|
|
|
|
Large downloads may take a few seconds to assemble, so there may be a delay
|
|
between clicking the download button and the download starting.
|
|
|
|
### `Forbidden media source identifier`
|
|
|
|
- If you are using a custom `client_id` setting in your `frigate.yml` file (the
|
|
configuration file for the Frigate backend itself), the card will auto-detect
|
|
it from the camera entity. If auto-detection fails (e.g. no `camera_entity`
|
|
is configured), set it manually -- see [Frigate engine
|
|
configuration](configuration/cameras/engine.md?id=frigate).
|
|
- You must have the `Enable the media browser` option enabled for the Frigate
|
|
integration, in order for media fetches to work for the card. Media fetches
|
|
are used to fetch events / clips / snapshots, etc. If you just wish to use
|
|
live streams without media fetches, you can use the following configuration:
|
|
|
|
```yaml
|
|
live:
|
|
controls:
|
|
thumbnails:
|
|
mode: none
|
|
```
|
|
|
|
### Fullscreen doesn't work on iPhone
|
|
|
|
Unfortunately, [iOS does not support the Javascript fullscreen
|
|
API](https://caniuse.com/fullscreen) on the iPhone, which severely limits the
|
|
fullscreen functionality available. On iPhone, fullscreen is only possible of
|
|
the selected video element. As a result, there will be no menu, status bar, grid
|
|
support, gallery / timeline support, nor support for non-video based [live
|
|
providers](./configuration/cameras/live-provider.md) such as `image` or `jsmpeg`
|
|
-- exclusively viewing a selected live video or media video in fullscreen.
|
|
|
|
The card will only show the fullscreen menu button when fullscreen can usefully
|
|
be activated, which means for certain views on the iPhone it will be absent.
|
|
|
|
### Custom `go2rtc` server only works on Home Network
|
|
|
|
This card runs in your browser, and (if configured) attempts to opens a direct
|
|
connection to a `go2rtc` server. If you are manually specifying a custom server
|
|
using the [`url`](./configuration/cameras/live-provider.md?id=go2rtc) option,
|
|
your browser may only be able to access that server when you're on the same
|
|
network, and/or when both Home Assistant and the `go2rtc` server are both
|
|
accessed over `http` or both over `https`.
|
|
|
|
To automatically proxy the connection via the Home Assistant process instead
|
|
(ensuring that if you can access the card, you'll always have access to the
|
|
`go2rtc` server), optionally install
|
|
[hass-web-proxy-integration](https://github.com/dermotduffy/hass-web-proxy-integration)
|
|
and your connection will be automatically proxied. See
|
|
[proxying](./configuration/cameras/README.md?id=proxy).
|
|
|
|
### iOS App not updating after card version change
|
|
|
|
Try resetting the app frontend cache:
|
|
|
|
- `Configuration -> Companion App -> Debugging -> Reset frontend cache`
|
|
|
|
### Javascript console errors
|
|
|
|
#### `[Violation] Added non-passive event listener to a scroll-blocking [...] event`
|
|
|
|
This card uses [visjs](https://github.com/visjs/vis-timeline) -- a timeline
|
|
library -- to show camera timelines. This library currently uses non-passive
|
|
event-listeners. These warnings can be safely ignored in this instance and
|
|
cannot easily be fixed in the underlying library.
|
|
|
|
### Microphone menu button not shown
|
|
|
|
The microphone menu button will only appear if both enabled (see [Menu Button
|
|
configuration](configuration/menu.md?id=available-buttons)) and if the media
|
|
that is currently loaded supports 2-way audio. See [Using 2-way
|
|
audio](usage/2-way-audio.md) for more information about the requirements that
|
|
must be followed.
|
|
|
|
### Picture-in-Picture only shows video but not other card controls
|
|
|
|
Picture-in-Picture (PIP) uses the browser's [native video PIP
|
|
API](https://caniuse.com/picture-in-picture) which floats the raw video element
|
|
into a small window. This means:
|
|
|
|
- **No card UI in the PIP window.** Only the video itself is shown -- no menu,
|
|
status bar, timeline, or other card elements. The card remains fully
|
|
functional on the dashboard behind it.
|
|
- **Limited browser support.** Not all browsers support the PIP API. See
|
|
[Can I use: Picture-in-Picture](https://caniuse.com/picture-in-picture) for
|
|
current browser compatibility.
|
|
- **Non-video live providers are not supported.** Providers such as `image` or
|
|
`jsmpeg` do not use a native `<video>` element so PIP is unavailable for
|
|
these.
|
|
|
|
A more fully featured PIP mode (showing the entire card in a floating window)
|
|
was explored using the experimental [Document Picture-in-Picture
|
|
API](https://caniuse.com/mdn-api_documentpictureinpicture), however it proved
|
|
unworkable: Home Assistant state updates cannot reach a card in a separate
|
|
document, and browser-managed styles (`adoptedStyleSheets`) are cleared when
|
|
elements move between documents -- resulting in an unstyled, non-updating card.
|
|
|
|
### New version not working in Chrome
|
|
|
|
When upgrading the card it's recommended to reset the frontend cache. Sometimes
|
|
clearing site data in Chrome settings isn't enough.
|
|
|
|
- Press F12 to display `Dev Console` in Chrome then right click on the refresh
|
|
icon and select `Empty Cache and Hard Reload`
|
|
|
|
### Static image URL with credentials doesn't load
|
|
|
|
Your browser will not allow a page/script (like this card) to pass credentials
|
|
to a cross-origin (different host) image URL for security reasons. There is no
|
|
way around this unless you could also control the webserver that is serving the
|
|
image to specifically allow `crossorigin` requests (which is typically not the
|
|
case for an image served from a camera, for example). The stock Home Assistant
|
|
Picture Glance card has the same limitation, for the same reasons.
|
|
|
|
### Status "popup" continually popping up
|
|
|
|
Status popup can be disabled with this configuration:
|
|
|
|
```yaml
|
|
status_bar:
|
|
style: none
|
|
```
|
|
|
|
### Too many releases!
|
|
|
|
A new version of this card is [automatically
|
|
released](./developing.md?id=release-philosophy) on each change ("Pull
|
|
Request"). This means features and fixes are available immediately! However, it
|
|
also means there may be visual notifications in Home Assistant frequently
|
|
recommending update and some users find this annoying.
|
|
|
|
The topic of intentionally doing fewer releases has been discussed fairly
|
|
extensively
|
|
([#1781](https://github.com/dermotduffy/advanced-camera-card/issues/1781),
|
|
[#2072](https://github.com/dermotduffy/advanced-camera-card/issues/2072)) but it
|
|
always comes down to some users (and this developer!) like it instant / often,
|
|
others like it slower / rarer.
|
|
|
|
As a workaround for those that this bothers, the visual notification (the 'dot')
|
|
to remind users to upgrade can be disabled by disabling the matching `update`
|
|
entity provided by HACS. The entity is usually called
|
|
`update.advanced_camera_card_update`. To disable it:
|
|
|
|
- Navigate to: `Settings -> Devices & Services -> HACS -> # Entities -> Advanced Camera Card update`
|
|
- Click the settings "cog"
|
|
- Set "Enabled" to off
|
|
|
|
### Unknown Frigate instance `frigate`
|
|
|
|
e.g. `API error whilst subscribing to events for unknown Frigate instance frigate`
|
|
|
|
The card auto-detects a custom `client_id` from the camera entity, so this
|
|
error usually means auto-detection couldn't run (no `camera_entity` configured)
|
|
or the entity doesn't expose a `client_id` attribute. Set it manually via the
|
|
`client_id` parameter:
|
|
|
|
```yaml
|
|
cameras:
|
|
- camera_entity: camera.my_frigate_camera
|
|
frigate:
|
|
client_id: my-frigate
|
|
```
|
|
|
|
See [Frigate engine configuration](configuration/cameras/engine.md?id=frigate)
|
|
for more details.
|
|
|
|
If you're not using a custom `client_id`, your Frigate integration is likely not
|
|
installed correctly.
|
|
|
|
### `webrtc_card` unloads in the background
|
|
|
|
[AlexxIT's WebRTC Card](https://github.com/AlexxIT/WebRTC) which is embedded by
|
|
the `webrtc_card` live provider internally disconnects the stream when the
|
|
browser tab is changed (regardless of any Advanced Camera Card configuration settings,
|
|
e.g. `lazy_unload`). To allow the stream to continue running in the background,
|
|
pass the `background` argument to the `webrtc_card` live provider as shown
|
|
below. This effectively allows the Advanced Camera Card to decide whether or not to
|
|
unload the stream.
|
|
|
|
```yaml
|
|
live:
|
|
webrtc_card:
|
|
background: true
|
|
```
|