@sequencemedia/music-library-parser 1.1.183 → 1.1.184
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/RUST.md +132 -0
- package/husky.mjs +2 -0
- package/package.json +3 -3
- package/src/js/library/playlists/transform/index.mjs +1 -1
- package/src/js/transform/index.mjs +25 -22
package/docs/RUST.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Rust transformation options
|
|
2
|
+
|
|
3
|
+
These notes record suggestions for replacing the Java/Saxon dependency used to
|
|
4
|
+
transform an Apple Music `Library.xml` export. They describe possible approaches;
|
|
5
|
+
no Rust implementation has been added.
|
|
6
|
+
|
|
7
|
+
## Existing transformations
|
|
8
|
+
|
|
9
|
+
The stylesheets currently handle three main tasks:
|
|
10
|
+
|
|
11
|
+
- [JSON conversion](../src/xsl/to-json.xsl): convert plist dictionaries, arrays,
|
|
12
|
+
integers, booleans, strings, dates, and data to JSON. The entry stylesheets
|
|
13
|
+
select the entire library, tracks, or playlists.
|
|
14
|
+
- [Album exports](../src/xsl/library/tracks.xsl): filter audio tracks, group by
|
|
15
|
+
album artist or artist and album, handle compilations separately, sort by disc
|
|
16
|
+
and track number, and write M3U8 files.
|
|
17
|
+
- [Playlist exports](../src/xsl/library/playlists.xsl): filter playlists, resolve
|
|
18
|
+
parent folders and track IDs, handle duplicate names, and write M3U8 files.
|
|
19
|
+
|
|
20
|
+
The JavaScript wrappers also expose parsed JavaScript objects and convert those
|
|
21
|
+
objects to `Map`, `Set`, and `Date` instances.
|
|
22
|
+
|
|
23
|
+
## Approaches
|
|
24
|
+
|
|
25
|
+
There are two broad directions: express the transformation rules in Rust, or
|
|
26
|
+
retain XSL stylesheets and use a Rust XSLT engine. Writing transformation rules in
|
|
27
|
+
Rust does not require writing a custom XML parser.
|
|
28
|
+
|
|
29
|
+
| Approach | Benefits | Tradeoffs |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| `plist` with Rust transformation code | Parses Apple's format directly; supports dynamic values and typed deserialization. Recommended starting point. | Filtering, grouping, sorting, naming, and output rules need to be translated into Rust. A complete value tree retains the library in memory. |
|
|
32
|
+
| `quick-xml` with custom plist parsing and transformation code | Gives control over incremental parsing and which metadata is retained. | Requires handling plist key/value pairing and types explicitly, as well as implementing the transformation rules. |
|
|
33
|
+
| `xrust` with adapted XSL stylesheets | Retains the stylesheet approach. | Requires a compatibility investigation; Java extension calls need replacing, and the required XSLT features must be verified. |
|
|
34
|
+
|
|
35
|
+
## Suggested crates
|
|
36
|
+
|
|
37
|
+
### `plist`
|
|
38
|
+
|
|
39
|
+
[`plist`](https://docs.rs/plist/latest/plist/) is the first choice for reading
|
|
40
|
+
`Library.xml`. It understands the alternating `<key>` and value elements in Apple
|
|
41
|
+
property lists, including dictionaries, arrays, dates, and binary data.
|
|
42
|
+
|
|
43
|
+
Use `plist::Value` when arbitrary library fields should be retained, or Serde
|
|
44
|
+
deserialization into Rust structs when a defined subset of fields is sufficient.
|
|
45
|
+
|
|
46
|
+
### `serde` and `serde_json`
|
|
47
|
+
|
|
48
|
+
[`serde`](https://serde.rs/) and
|
|
49
|
+
[`serde_json`](https://docs.rs/serde_json/latest/serde_json/index.html) provide the
|
|
50
|
+
JSON output layer. They support typed structures and dynamic JSON values, and
|
|
51
|
+
replace the handwritten JSON escaping in the current stylesheets. JSON can be
|
|
52
|
+
written to a string or directly to a writer.
|
|
53
|
+
|
|
54
|
+
Define the mapping from plist types to JSON explicitly, particularly for dates
|
|
55
|
+
and binary data, rather than assuming default serialization matches the XSL.
|
|
56
|
+
|
|
57
|
+
### `unicode-normalization`
|
|
58
|
+
|
|
59
|
+
[`unicode-normalization`](https://docs.rs/unicode-normalization/latest/unicode_normalization/trait.UnicodeNormalization.html)
|
|
60
|
+
provides `.nfd()`, corresponding to the canonical decomposition used by
|
|
61
|
+
`seq:normalize-for-path`. Apply the existing character removal, replacement, and
|
|
62
|
+
whitespace rules after decomposition.
|
|
63
|
+
|
|
64
|
+
### `percent-encoding` or `url`
|
|
65
|
+
|
|
66
|
+
[`percent-encoding`](https://docs.rs/percent-encoding/latest/percent_encoding/)
|
|
67
|
+
fits the percent-decoding currently performed through Java's `URLDecoder`.
|
|
68
|
+
Percent decoding preserves literal `+` characters, matching the intent of the
|
|
69
|
+
stylesheet's workaround for form-style decoding.
|
|
70
|
+
|
|
71
|
+
[`url`](https://docs.rs/url/latest/url/struct.Url.html#method.to_file_path) is an
|
|
72
|
+
alternative when explicit URL parsing and conversion from `file:` URLs to native
|
|
73
|
+
paths are desired. Check its behavior against the existing decode-and-strip
|
|
74
|
+
rules before adopting it as a replacement.
|
|
75
|
+
|
|
76
|
+
### `quick-xml`
|
|
77
|
+
|
|
78
|
+
[`quick-xml`](https://docs.rs/quick-xml/latest/quick_xml/) is an alternative to
|
|
79
|
+
`plist` when large libraries justify incremental XML parsing. Its pull reader
|
|
80
|
+
allows processing records while retaining only the information needed later.
|
|
81
|
+
|
|
82
|
+
Album grouping and playlist track lookups still require retained state, so
|
|
83
|
+
streaming XML does not eliminate all memory use. Prefer this approach when
|
|
84
|
+
library size or measured memory use warrants the additional parsing code.
|
|
85
|
+
|
|
86
|
+
## M3U8 output
|
|
87
|
+
|
|
88
|
+
The current output only needs `#EXTM3U`, `#EXTINF` duration/title entries, and
|
|
89
|
+
track paths. `std::io::Write` and `BufWriter` should be sufficient initially.
|
|
90
|
+
|
|
91
|
+
[`m3u8-rs`](https://docs.rs/m3u8-rs/latest/m3u8_rs/) focuses on HTTP Live Streaming
|
|
92
|
+
playlists, so it is not the first choice for these local music playlists.
|
|
93
|
+
|
|
94
|
+
## Retaining XSL with `xrust`
|
|
95
|
+
|
|
96
|
+
[`xrust`](https://docs.rs/xrust/latest/xrust/) is worth investigating if retaining
|
|
97
|
+
the stylesheets is a priority. Its documented XSLT implementation is incomplete;
|
|
98
|
+
treat it as a compatibility experiment rather than an established replacement
|
|
99
|
+
for Saxon.
|
|
100
|
+
|
|
101
|
+
The existing stylesheets use grouping, custom functions, multiple result
|
|
102
|
+
documents, imports, and Java extension calls. Verify support for each required
|
|
103
|
+
feature. Calls to `java.net.URLDecoder` would need replacement.
|
|
104
|
+
|
|
105
|
+
## Compatibility details
|
|
106
|
+
|
|
107
|
+
Before implementing a replacement, decide which existing behaviors must be
|
|
108
|
+
preserved:
|
|
109
|
+
|
|
110
|
+
- **Binary data:** the JSON stylesheet emits `<data>` as an array of base64 text
|
|
111
|
+
lines. `plist::Value::Data` contains decoded bytes and does not retain the
|
|
112
|
+
original base64 line wrapping. Exact compatibility requires deliberate handling.
|
|
113
|
+
- **Dates:** the JSON stylesheet preserves date text as strings. The JavaScript
|
|
114
|
+
`toES` conversion subsequently creates `Date` instances from matching strings.
|
|
115
|
+
- **Path normalization:** the stylesheets remove U+0300–U+036F after NFD
|
|
116
|
+
decomposition. Removing all Unicode combining marks would change the behavior.
|
|
117
|
+
Playlist and album filename rules also differ over double quotes.
|
|
118
|
+
- **Ordering:** retain playlist item order and duplicates, and reproduce album
|
|
119
|
+
sorting by disc and track number. A Rust set should not replace a playlist's
|
|
120
|
+
ordered list of track references.
|
|
121
|
+
- **Track locations:** preserve literal plus signs and check percent decoding,
|
|
122
|
+
`file:` URL handling, and non-file locations.
|
|
123
|
+
- **M3U8 formatting:** the stylesheets emit carriage-return-only line endings.
|
|
124
|
+
Durations are floored from milliseconds to seconds; zero and missing values
|
|
125
|
+
produce `-1`.
|
|
126
|
+
- **Selection and naming:** preserve the album and playlist filters, compilation
|
|
127
|
+
handling, parent folder resolution, and duplicate-name suffix rules where
|
|
128
|
+
compatibility is required.
|
|
129
|
+
|
|
130
|
+
The recommended starting point is `plist`, `serde`, `serde_json`,
|
|
131
|
+
`unicode-normalization`, and `percent-encoding`, with ordinary Rust collections
|
|
132
|
+
for grouping and lookups and standard buffered I/O for M3U8 output.
|
package/husky.mjs
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sequencemedia/music-library-parser",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.184",
|
|
4
4
|
"description": "Parse Apple Music Library XML to JSON, JS, ES, or M3U",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"music",
|
|
@@ -48,8 +48,8 @@
|
|
|
48
48
|
"rimraf": "^6.1.4"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@sequencemedia/eslint-config-standard": "0.3.
|
|
52
|
-
"eslint": "10.
|
|
51
|
+
"@sequencemedia/eslint-config-standard": "0.3.4",
|
|
52
|
+
"eslint": "10.15.0",
|
|
53
53
|
"globals": "^17.14.0",
|
|
54
54
|
"husky": "^9.1.7"
|
|
55
55
|
},
|
|
@@ -21,7 +21,7 @@ import hereIAm from '#where-am-i'
|
|
|
21
21
|
|
|
22
22
|
const error = debug('@sequencemedia/music-library-parser:to-json:error')
|
|
23
23
|
|
|
24
|
-
const xsl = join(hereIAm, 'src/xsl/library/
|
|
24
|
+
const xsl = join(hereIAm, 'src/xsl/library/playlists/to-json.xsl')
|
|
25
25
|
const DESTINATION = join(hereIAm, '.music-library/playlists.json')
|
|
26
26
|
|
|
27
27
|
/**
|
|
@@ -1,28 +1,31 @@
|
|
|
1
|
-
|
|
2
|
-
Object.entries(o)
|
|
3
|
-
.forEach(([key, value] = []) => {
|
|
4
|
-
switch ((value || false).constructor) {
|
|
5
|
-
case Object:
|
|
6
|
-
m.set(key, transformObjectToMap(value, new Map()))
|
|
7
|
-
break
|
|
1
|
+
const DATE = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/
|
|
8
2
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
function reduceSet (s, o) {
|
|
4
|
+
return s.add(transform(o))
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
function reduceMap (m, [key, value]) {
|
|
8
|
+
switch ((value || false).constructor) {
|
|
9
|
+
case Array:
|
|
10
|
+
return m.set(key, transformArrayToSet(value, new Set()))
|
|
11
|
+
|
|
12
|
+
case Object:
|
|
13
|
+
return m.set(key, transformObjectToMap(value, new Map()))
|
|
14
|
+
}
|
|
12
15
|
|
|
13
|
-
|
|
14
|
-
m.set(key, /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/.test(value) ? new Date(value) : value)
|
|
15
|
-
break
|
|
16
|
-
}
|
|
17
|
-
})
|
|
18
|
-
return m
|
|
16
|
+
return m.set(key, DATE.test(value) ? new Date(value) : value)
|
|
19
17
|
}
|
|
20
18
|
|
|
21
|
-
export
|
|
22
|
-
a.
|
|
23
|
-
s.add(transform(o))
|
|
24
|
-
})
|
|
25
|
-
return s
|
|
19
|
+
export function transformArrayToSet (a, s) {
|
|
20
|
+
return a.reduce(reduceSet, s)
|
|
26
21
|
}
|
|
27
22
|
|
|
28
|
-
export
|
|
23
|
+
export function transformObjectToMap (o, m) {
|
|
24
|
+
return Object.entries(o).reduce(reduceMap, m)
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function transform (v) {
|
|
28
|
+
return Array.isArray(v)
|
|
29
|
+
? transformArrayToSet(v, new Set())
|
|
30
|
+
: transformObjectToMap(v, new Map())
|
|
31
|
+
}
|