Repository navigation
plexdo build merge
plexdo-build-merge - mix two playlists into a new one at a ratio
plexdo build-merge USER NAME FIRST SECOND [--ratio A:B] [-s] [-U] [-o] [--m3u PATH [-p PREFIX]] [-u TARGET | -a] [GLOBAL OPTIONS]
Mixes two of USER's playlists into a new playlist titled NAME, taking items from each in turn at a ratio: by default one from FIRST, then one from SECOND, and so on. With --ratio 2:1 it takes two from FIRST, then one from SECOND. Each playlist keeps its own order, and both are left as they were.
A playlist has run out on the first turn it has nothing to give. By default the rest of the other then follows on its own, so nothing is left out; --verbose says how many items that is. With -s the result stops there instead, ending with the last turn both playlists took part in, so all of it keeps the ratio. Playlists whose sizes match the ratio, such as 20 and 10 items at 2:1, run out together, and -s changes nothing.
Both playlists are read before anything is written, so either may also be NAME: with -o, build-merge 0 Mix Mix Extras -o mixes Extras into Mix.
By default an item in both playlists appears twice, as Plex permits; -U keeps only its first appearance. An empty playlist is reported with a warning, since a mistyped name that matched the wrong playlist looks exactly like one that happens to be empty; the result is then the other playlist unchanged, or, with -s, nothing.
The whole list is built before anything is created, then shown as a numbered preview, and the playlist is created in a single request. Nothing is created when the result is empty.
By default NAME is created on USER's own account. -u creates it for another user instead, and -a for every user. See USERS below.
USER
Whose playlists are mixed, by numeric user ID or title; 0 is the admin account. See plexdo-conventions(7).
NAME
The title of the new playlist.
FIRST, SECOND
The two playlists, by title or ratingKey. A value made only of digits is always taken as a ratingKey. FIRST starts the result. They may be the same playlist.
--ratio A:B
Take A items from FIRST, then B from SECOND, in turn. Both are whole numbers above 0. The default is 1:1.
-s, --stop-short
Stop when either playlist runs out, leaving out the rest of the other. A turn cut short because a playlist had fewer items left than the ratio asks for still counts: the result stops at the first turn a playlist has nothing at all to give.
-U, --unique
Skip an item already taken, so an item in both playlists, or twice in one, is listed once, where it first appears. The next item of the same playlist takes the place of one skipped, so the ratio still holds. Items are matched by ratingKey rather than title, so two episodes sharing a title are both kept.
-o, --overwrite
Replace an existing playlist titled NAME. Without it, a taken name is refused: see OPTION INTERACTIONS.
--m3u PATH
Also write the mixed items to an M3U file at PATH, replacing any file already there. A leading ~ is expanded. Each entry carries the item's length in seconds (-1 when unknown), its title, and the path of its file.
-p, --prefix PREFIX
Rewrite the paths written by --m3u so the server's library root is replaced by PREFIX. See REWRITING EXPORTED PATHS in plexdo-conventions(7).
-u, --user TARGET
Create NAME for this user rather than for USER, by numeric user ID or title; 0 is the admin account. The playlists are still read from USER.
-a, --all-users
Create NAME for every user on the server, the admin account included. The playlists are still read from USER.
With -u or -a, the mixed list is printed once, followed by one line per user as each completes: created, replaced, skipped (the title is taken, or the server will not act for that user), or failed. Nothing that goes wrong for one user stops the others.
-f, --format FORMAT; --json
Choose the format of the preview. With -u or -a, a machine-readable format carries one record per user instead: user, id, status, playlist, and detail.
-W, --wide
Never truncate the preview table; titles are what would shrink.
--throttle SECONDS
Paces -a when there are more than 50 users. 0 turns pacing off.
-v, --verbose; --debug
--verbose reports each playlist's size as it is read, how many items follow unmixed once the other playlist runs out, or with -s how many were left out, how many repeats -U skipped, the size of the result, its creation or replacement, and under -a how many users were served.
--debug-log PATH
Appends what --debug reports to PATH instead, with the run profiled: each phase's time, every HTTP request and its wait, CPU and memory use, and function run times. See DEBUG LOG in plexdo-conventions(7).
--dry-run
Read, mix, and preview, check NAME as usual, and stop without creating or replacing anything. Under -u or -a, each user's line says what would have happened. --m3u still writes its file.
-V, --version; -h, --help
Print the version, or this command's help, and exit.
·
-u and -a are mutually exclusive; giving both is an error.
·
USER always names where the playlists are read from; -u and -a only change where NAME is created.
·
Without -o, a playlist already titled NAME is refused. On USER's account, the default, that is an error, reported before the preview, and nothing is created or removed. Under -u or -a it makes that user skipped, and the others carry on.
·
-o replaces the existing playlist, which may be FIRST or SECOND: both are read first, so their items are not lost.
·
--ratio 1:1 and --ratio 3:3 differ: the second takes runs of three.
·
-s with an empty playlist gives an empty result, so nothing is created.
·
Under -U and -s together, a playlist with only repeats left has run out: it has nothing new to give.
·
-u is --user, the account NAME is created for; -U is --unique.
·
--prefix only changes the paths written by --m3u; without --m3u it has no effect.
·
--m3u is written once, whichever users the playlist is created for, and is written under --dry-run too.
0 on success. Under -u or -a, 0 even when some users were skipped or failed; their lines say so. 1 when USER, FIRST, or SECOND is not found, when the result is empty, when USER has nothing shared and cannot be acted on, or when NAME is taken without -o on USER's account. 2 when --ratio is not two whole numbers above 0, or -u and -a are both given. See plexdo-conventions(7).
Alternate two playlists, one item from each:
plexdo build-merge 0 "Date Night" "Her Picks" "His Picks"
Two cartoons for every film, checking the result first:
plexdo build-merge 0 "Saturday" Cartoons Films --ratio 2:1 --dry-run
Two shows for every film, ending with the last film, and without an episode the two playlists share appearing twice:
plexdo build-merge 0 "Weekend" Shows Films --ratio 2:1 -s -U
Mix new finds into an existing playlist, one for every three, in place:
plexdo build-merge 0 Mix Mix "New Finds" --ratio 3:1 -o
Mix playlists by ratingKey, and give the result to every user:
plexdo build-merge 0 "Holiday Mix" 9001 9017 -a
plexdo-build-concatenated(1), plexdo-build-interleaved(1), plexdo-list-playlists(1), plexdo-conventions(7), plexdo(1)