feat: Add folder title matching and parsing (#2067)
This is a breaking change for users of the [experimental 'folder' functionality](https://card.camera/#/configuration/folders). Related: #1748
This commit is contained in:
Dermot Duffy
+199
-22
@@ -21,7 +21,7 @@ folders:
|
||||
|
||||
## `ha`
|
||||
|
||||
Used to specify a Home Assistant media folder.
|
||||
Used to specify a path to Home Assistant media.
|
||||
|
||||
```yaml
|
||||
folders:
|
||||
@@ -30,19 +30,29 @@ folders:
|
||||
# [...]
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `url` | | An optional Home Assistant `Media` browser URL to use as the query base. If `path` is also specified, those matchers are applied against folders "below" the folder specified in `url`. |
|
||||
| `path` | [`{ id: media-source:// }`] | An optional array of matchers to dynamically compare against the Home Assistant media folder hierarchy. See below. |
|
||||
| Option | Default | Description |
|
||||
| ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `url` | | An optional Home Assistant `Media` browser URL to use as the query base. If `path` is also specified, those matchers/parsers are applied against folders "below" the folder specified in `url`. |
|
||||
| `path` | [`{ id: media-source:// }`] | An optional array of parsers and matchers to dynamically compare and extract metadata from the Home Assistant media folder hierarchy. See below. |
|
||||
|
||||
?> `url` is never fetched, nor sent over the network. It is only processed
|
||||
locally in your browser. The host part of the URL can optionally be removed.
|
||||
|
||||
### `path`
|
||||
|
||||
An array of matchers to navigate "down" a folder hierarchy. If `url` is also
|
||||
specified, matchers are applied starting at that folder, otherwise they are
|
||||
applied at the media source root (i.e. `media-source://`).
|
||||
An array of values that represents the path to a Home Assistant media item, e.g.
|
||||
a media item at a path of `one/two/three` would be represented by a path array
|
||||
of length three.
|
||||
|
||||
| Option | Default | Description |
|
||||
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | | An optional exact media item to select, usually the parent of where `matchers` and `parsers` should apply. |
|
||||
| `matchers` | | An optional array of matchers to evaluate whether to return a given media item. If no matcher is specified, everything in the given folder matches. See below. |
|
||||
| `parsers` | | An optional array of parsers that extract data out of a media item. See below. |
|
||||
|
||||
If `url` is also specified, parsers/matchers are applied starting at that
|
||||
folder, otherwise they are applied from the media source root (i.e.
|
||||
`media-source://`).
|
||||
|
||||
```yaml
|
||||
folders:
|
||||
@@ -52,21 +62,93 @@ folders:
|
||||
# [...]
|
||||
```
|
||||
|
||||
| Option | Default | Description |
|
||||
| ---------- | ------- | ------------------------------------------------------ |
|
||||
| `id` | | An optional media source `id` to match against. |
|
||||
| `title` | | An optional title name to match against. |
|
||||
| `title_re` | | An optional title regular expression to match against. |
|
||||
?> To match everything at a given level whilst parsing nothing would simply be
|
||||
represented by an empty object `{}`
|
||||
|
||||
?> Specifying multiple `path` matchers (other than `id`) requires a query at
|
||||
each level of the folder hierarchy and is slower than directly specifying the
|
||||
media source `id` (if known) or the `url` of the folder.
|
||||
#### Matchers
|
||||
|
||||
#### Examples
|
||||
Matches are used to match a given media item. Multiple matchers may be specified
|
||||
to perform multiple tests. A given match may match multiple items. If an item
|
||||
does not match, it will not be returned to the user nor (in case of subfolders)
|
||||
feature in future traversals.
|
||||
|
||||
See [Folder Examples](../examples.md?id=folders).
|
||||
##### Matcher: `title`
|
||||
|
||||
#### Understanding Media Source IDs and "parent folders"
|
||||
Match against the media item title.
|
||||
|
||||
```yaml
|
||||
type: title
|
||||
# [...]
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ---------------------------------------------------------------------- |
|
||||
| `type` | Must be `title`. |
|
||||
| `regexp` | An optional regular expression to matches against the title. |
|
||||
| `title` | An optional exact value (case-sensitive) to matches against the title. |
|
||||
|
||||
#### Parsers
|
||||
|
||||
Parsers are used to extract data from a media item (e.g. an event start time).
|
||||
Parsed data is propagated down the hierarcy, e.g. a given media item inherits
|
||||
the metadata of its parents.
|
||||
|
||||
##### Parser `date` / `startdate`
|
||||
|
||||
Parses a start date from a media title. `date` is an convenient alias for
|
||||
`startdate`.
|
||||
|
||||
```yaml
|
||||
type: date
|
||||
# [...]
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `type` | Must be `date` or `startdate`. |
|
||||
| `format` | A [`date-fns` format string](https://date-fns.org/docs/parse). If unspecified, [`any-date-parser`](https://www.npmjs.com/package/any-date-parser) is used to parse a date and/or time which covers many common cases. In the event of missing or inaccurate metadata, specifying a precise format may help. |
|
||||
| `regexp` | An optional regular expression to first match the title against before parsing. May be used to match against a subset of the string, see [tip below](#regular-expression-matching). |
|
||||
|
||||
## Advanced
|
||||
|
||||
### Regular Expression Matching
|
||||
|
||||
For `matchers` and `parsers` that support the `regexp` option, it may be used to
|
||||
compare against only a portion of the media title. By default, that portion is
|
||||
whatever part of the title matches the given regexp. For extra-precision, use a
|
||||
named regexp group called `value`.
|
||||
|
||||
For example, pulling time values out of a media title, before parsing them with
|
||||
a `HH:mm:ss` format.
|
||||
|
||||
```yaml
|
||||
parsers:
|
||||
- type: date
|
||||
regexp: "\d{2}:\d{2}:\d{2}"
|
||||
format: HH:mm:ss
|
||||
```
|
||||
|
||||
Similarly, this example uses a named group to refer to the text at the end of
|
||||
the title.
|
||||
|
||||
```yaml
|
||||
parsers:
|
||||
- type: date
|
||||
regexp: '^Time: (?<value>.*)+'
|
||||
format: HH:mm:ss
|
||||
```
|
||||
|
||||
In this contrived example, the regular expression is used to extract either
|
||||
`Low` or `High` from the title, and then match only the `High` entry.
|
||||
|
||||
```yaml
|
||||
matchers:
|
||||
- type: title
|
||||
regexp: '(?<value>Low|High) Resolution'
|
||||
title: High
|
||||
```
|
||||
|
||||
### Understanding Media Source IDs and "parent folders"
|
||||
|
||||
Home Assistant Media Source IDs are typically long integration-specific non-user
|
||||
friendly strings that refer to a media item, or folder of media items. Media
|
||||
@@ -74,6 +156,93 @@ source "folders" do not have an intrinsic parent as with filesystem folders,
|
||||
rather a trail is built as the user navigates "downwards" -- but anything could
|
||||
theoretically be the parent of anything.
|
||||
|
||||
## Worked Example
|
||||
|
||||
Imagine a media folder hierarchy that starts with a choice of resolution (Low or
|
||||
High). Lets start by specifying a basic folder referring to the URL of the Home
|
||||
Assistant Media Browser for that folder (via copy and paste of the URL from
|
||||
another browser window with the folder open):
|
||||
|
||||
```yaml
|
||||
folders:
|
||||
- type: ha
|
||||
ha:
|
||||
url: >-
|
||||
/media-browser/browser/app%2Cmedia-source%3A%2F%2Freolink/playlist%2Cmedia-source%3A%2F%2Freolink%2FCAM%7C01J8XAATNH77WE5D654K07KY1F%7C0
|
||||
```
|
||||
|
||||
The result:
|
||||
|
||||
|
||||
|
||||
Now lets include selecting the High resolution folder:
|
||||
|
||||
```yaml
|
||||
folders:
|
||||
- type: ha
|
||||
ha:
|
||||
url: >-
|
||||
/media-browser/browser/app%2Cmedia-source%3A%2F%2Freolink/playlist%2Cmedia-source%3A%2F%2Freolink%2FCAM%7C01J8XAATNH77WE5D654K07KY1F%7C0
|
||||
# Added below:
|
||||
path:
|
||||
- matchers:
|
||||
- type: title
|
||||
title: High resolution
|
||||
```
|
||||
|
||||
The result:
|
||||
|
||||
|
||||
|
||||
The next step is to navigate down to the date folder, parsing the date as we go
|
||||
(auto-detecting the format):
|
||||
|
||||
```yaml
|
||||
folders:
|
||||
- type: ha
|
||||
ha:
|
||||
url: >-
|
||||
/media-browser/browser/app%2Cmedia-source%3A%2F%2Freolink/playlist%2Cmedia-source%3A%2F%2Freolink%2FCAM%7C01J8XAATNH77WE5D654K07KY1F%7C0
|
||||
path:
|
||||
- matchers:
|
||||
- type: title
|
||||
title: High resolution
|
||||
# Added below:
|
||||
- parsers:
|
||||
- type: startdate
|
||||
```
|
||||
|
||||
The result:
|
||||
|
||||
|
||||
|
||||
The final step is to navigate down to the media item themselves, automatically parsing the time out of them:
|
||||
|
||||
```yaml
|
||||
folders:
|
||||
- type: ha
|
||||
ha:
|
||||
url: >-
|
||||
/media-browser/browser/app%2Cmedia-source%3A%2F%2Freolink/playlist%2Cmedia-source%3A%2F%2Freolink%2FCAM%7C01J8XAATNH77WE5D654K07KY1F%7C0
|
||||
path:
|
||||
- matchers:
|
||||
- type: title
|
||||
title: High resolution
|
||||
- parsers:
|
||||
- type: startdate
|
||||
# Added below:
|
||||
- parsers:
|
||||
- type: startdate
|
||||
```
|
||||
|
||||
The final result:
|
||||
|
||||
|
||||
|
||||
### Other Examples
|
||||
|
||||
See [Folder Examples](../examples.md?id=folders).
|
||||
|
||||
## Fully expanded reference
|
||||
|
||||
[](common/expanded-warning.md ':include')
|
||||
@@ -85,7 +254,15 @@ folders:
|
||||
url: https://my-ha-instance.local/media-browser/browser/app%2Cmedia-source%3A%2F%2Ffrigate
|
||||
path:
|
||||
- id: 'media-source://'
|
||||
- title: 'Frigate'
|
||||
- title_re: 'Clips.*'
|
||||
- title_re: 'Person.*'
|
||||
- matchers:
|
||||
- type: title
|
||||
regexp: (?<value>.*) resolution
|
||||
title: Low
|
||||
- parsers:
|
||||
- type: date
|
||||
format: yyyy/MM/dd
|
||||
- parsers:
|
||||
- type: startdate
|
||||
format: HH:mm:ss
|
||||
regexp: 'File (?<value>.*)'
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user