@sequencemedia/music-library-parser 1.1.182 → 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 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
@@ -1,5 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ if (process.env.CI === 'true') process.exit(0)
4
+
3
5
  // @ts-ignore
4
6
  Promise.resolve(import('husky'))
5
7
  .then(({ default: husky }) => { husky() })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sequencemedia/music-library-parser",
3
- "version": "1.1.182",
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",
@@ -25,7 +25,7 @@
25
25
  },
26
26
  "license": "ISC",
27
27
  "engines": {
28
- "node": ">=22.11.0"
28
+ "node": ">=22.23.4"
29
29
  },
30
30
  "repository": {
31
31
  "type": "git",
@@ -48,8 +48,8 @@
48
48
  "rimraf": "^6.1.4"
49
49
  },
50
50
  "devDependencies": {
51
- "@sequencemedia/eslint-config-standard": "0.2.132",
52
- "eslint": "9.38.0",
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/tracks/to-json.xsl')
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
- export const transformObjectToMap = (o, m) => {
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
- case Array:
10
- m.set(key, transformArrayToSet(value, new Set()))
11
- break
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
- default:
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 const transformArrayToSet = (a, s) => {
22
- a.forEach((o) => {
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 const transform = (v) => Array.isArray(v) ? transformArrayToSet(v, new Set()) : transformObjectToMap(v, new Map())
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
+ }