From 98f045a70f479af30296aabcd555f1786fa601d8 Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Wed, 17 Dec 2025 13:57:56 +0000 Subject: [PATCH] docs: Improve general transform docs --- .../configuration/transforms/transforms.mdx | 33 +++++++++++++++++-- docsite/docusaurus.config.ts | 2 +- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/docsite/docs/configuration/transforms/transforms.mdx b/docsite/docs/configuration/transforms/transforms.mdx index 1bbd3194..6e74f9f0 100644 --- a/docsite/docs/configuration/transforms/transforms.mdx +++ b/docsite/docs/configuration/transforms/transforms.mdx @@ -371,7 +371,7 @@ Specifying these Rules is **not** the same as [configuring the Stage](#configuri ::: -### Flow Control +## Stage Flow Control {#flow-control} Stages may be optionally configured to **continue** to the next Stage or **stop** (end early) all subsequent Stages, based on the outcome of the currently running Stage. @@ -444,7 +444,7 @@ Specifying Flow Control is only necessary if the above assumptions are not true -### Conditional Modification +### Conditionally Run {#conditional-modification} [Stages](#stage) within a [Hook](#hook), and [Rules](#stage-rules) within each Stage, support a `when` object for testing **if they should be run.** @@ -452,6 +452,8 @@ The `when` object may have propertes for rule. Each property may be a string or All parts of an individual `when` clause must test true to "pass" but if **any** `when` clauses pass the Stage/Rule is processed. +If the `when` test does not pass then the Stage is [**skipped (`onSkip`)**](#flow-control). + ```json5 { "when": @@ -538,7 +540,7 @@ More succinctly: ## Logging -MS can log the output of Stage transformations if/when they occur. In the `playTransform` object of a Source/Client config use `log`: +MS can log a diff of Stage transformations if/when they occur. In the `playTransform` object of a Source/Client config use `log`: * `"log": true` => Output original play + final transformed output of last Stage in the array * `"log": "all"` => Output original play + final transformed output of **each** Stage in the array @@ -556,6 +558,31 @@ MS can log the output of Stage transformations if/when they occur. In the `playT } ``` +
+ +Example + +The output shows the diff between the previous stage (or original Play) and the current stage. In docker logs this is highlighted with diff syntax: + +```diff +[2025-12-17 08:53:10.467 -0500] DEBUG : [App] [Sources] [Lastfm - mylfm] [Play Transform] [preCompare] [VLDJJo] Transform Diff +- Original ++ musicbrainz-MyMB + + Title : Demons Theme Part II (original 12" mix) + Artists : LTJ Bukem + Album Artists: (None) +- Album : Producer 05: Rarities (Original 12" Version) ++ Album : Producer 05: Rarities (original 12" version) + Meta : + * brainz-album: 36759a8a-d3df-47da-a236-60f84fdc0cab ++ * brainz-artist: 28c1b7b7-355a-48b1-b2c4-75b8eb8080ef ++ * brainz-track: a0d51240-7ef1-4676-882e-be9f354075cb ++ * brainz-releaseGroup: e0cce74f-abcc-343b-9390-1673e4d57ce7 +``` + +
+ ## Examples See **Examples** sections in specific Stage docs (also in the sidebar): diff --git a/docsite/docusaurus.config.ts b/docsite/docusaurus.config.ts index 3247ca15..c7d9856c 100644 --- a/docsite/docusaurus.config.ts +++ b/docsite/docusaurus.config.ts @@ -202,7 +202,7 @@ const config: Config = { prism: { theme: themes.themes.github, darkTheme: themes.themes.dracula, - additionalLanguages: ['json','json5','typescript', 'docker', 'bash', 'ini'] + additionalLanguages: ['json','json5','typescript', 'docker', 'bash', 'ini', 'diff'] }, colorMode: { defaultMode: 'dark', -- 2.51.2