update(v6-migration): ensemble matching (#28)

* update(v6-migration): ensemble matching * Upcoming ensemble --------- Co-authored-by: ShanaryS <[email protected]>
cross-seed · Sep 27, 2024 · c69035d · c69035d
1 parent 24ccb1c
commit c69035d
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 3 deletions.
diff --git a/docs/basics/faq-troubleshooting.md b/docs/basics/faq-troubleshooting.md
@@ -273,7 +273,7 @@ We try to reduce unnecessary snatches of .torrent files as much as possible, but
 
 ### My partial matches from related searches are missing the same data, how can I only download it once?
 
-`cross-seed` is not aware of what matches will happen ahead of time, each is performed with zero knowledge of the previous or the following. As such it possible to have situations where a partial match when complete would become a perfect match for another otherwise partial match. This is usually neglibile since the missing data is small, but in cases where it is significant you can use the [inject](../reference/utils.md#cross-seed-inject) feature.
+`cross-seed` is not aware of what matches will happen ahead of time, each is performed with zero knowledge of the previous or the following. As such it possible to have situations where a partial match when complete would become a perfect match for another otherwise partial match. This is usually neglibile since the missing data is small, but in cases where it is significant such as with [seasonFromEpisodes](./options.md#seasonFromEpisodes), you can use the [inject](../reference/utils.md#cross-seed-inject) feature.
 
 If you have not recently deleted files in your [outputDir](./options.md#outputDir), then these torrents will still have their .torrent file present. If so, simply pick one torrent to complete the download on and that's it! `cross-seed` uses all possibles matches to source files with the inject job or when using `cross-seed inject`. It will automatically detect the newly downloaded files, link them to the other torrents, and trigger a recheck for those torrents.
 

diff --git a/docs/basics/options.md b/docs/basics/options.md
@@ -91,6 +91,7 @@ The configuration file uses JavaScript syntax, which means:
 | [`includeEpisodes`](#includeepisodes)               |              |
 | [`includeSingleEpisodes`](#includesingleepisodes)   |              |
 | [`includeNonVideos`](#includenonvideos)             |              |
+| [`seasonFromEpisodes`](#seasonfromepisodes)         |              |
 | [`fuzzySizeThreshold`](#fuzzysizethreshold)         |              |
 | [`excludeOlder`](#excludeolder)                     |              |
 | [`excludeRecentSearch`](#excluderecentsearch)       |              |
@@ -127,7 +128,8 @@ The configuration file uses JavaScript syntax, which means:
 | [`skipRecheck`](#skiprecheck)                       |              |
 | [`includeEpisodes`](#includeepisodes)               |              |
 | [`includeSingleEpisodes`](#includesingleepisodes)   |              |
-| [`includeNonVideos`](#includenonvideos)             |              |
+| [`includeNonVideos`](#includeNonvideos)             |              |
+| [`seasonFromEpisodes`](#seasonfromepisodes)         |              |
 | [`fuzzySizeThreshold`](#fuzzysizethreshold)         |              |
 | [`excludeOlder`](#excludeolder)                     |              |
 | [`excludeRecentSearch`](#excluderecentsearch)       |              |
@@ -751,6 +753,37 @@ includeSingleEpisodes: true,
 includeSingleEpisodes: false,
 ```
 
+### `seasonFromEpisodes`
+
+| Config file name     | CLI short form | CLI long form            | Format                         | Default |
+| -------------------- | -------------- | ------------------------ | ------------------------------ | ------- |
+| `seasonFromEpisodes` | `N/A`          | `--season-from-episodes` | `number` (decimal from 0 to 1) | `1`     |
+
+:::danger
+This is an upcoming feature for v6.
+:::
+
+`cross-seed` will also aggregate individual episodes into season packs
+for searching (when applicable) or to match with season packs from rss/announce.
+This will only match season packs where you have at least the specified ratio of episodes.
+`undefined` or `null` disables this feature.
+If enabled, values below 1 requires matchMode [partial](#matchmode).
+
+#### `seasonFromEpisodes` Examples (CLI)
+
+```shell
+cross-seed search --season-from-episodes 0.8 # will also combine episodes into season packs if you have at least 80% of the episodes
+cross-seed search # will not join episodes to season packs
+```
+
+#### `seasonFromEpisodes` Examples (Config file)
+
+```js
+seasonFromEpisodes: 0.8,
+
+seasonFromEpisodes: undefined,
+```
+
 ### `includeNonVideos`
 
 | Config file name   | CLI short form | CLI long form          | Format    | Default |

diff --git a/docs/v6-migration.md b/docs/v6-migration.md
@@ -76,10 +76,11 @@ You can grab the new [`config.template.js`](https://raw.githubusercontent.com/cr
 
 -   [`radarr`](./basics/options.md#radarr)
 
+-   [`seasonFromEpisodes`](./basics/options.md#seasonfromepisodes)
+
 -   [`skipRecheck`](./basics/options.md#skiprecheck) (_removed_)
 
 -   [`includeEpisodes`](#removed-includeepisodes) (_removed_)
-
 :::
 
 ### Stricter `config.js` Validation
@@ -329,6 +330,20 @@ The algorithms used for reverse lookup to match with your existing content has b
 
 With the new retrying capabilities in v6, the scenarios for a succesful [`announce`](./reference/api.md#post-apiannounce) response have expanded. A status code of `200` will now be returned even on injection failure since it will be later retried. `200` will also be returned if the torrent has already been injected, likely between [`autobrr`](./basics/faq-troubleshooting.md#how-can-i-use-autobrr-with-cross-seed) retries. A code of `200` should now be interpreted that a complete match was found, instead of a succesful injection. A code of `202` is still reported for incomplete torrents which allows for quicker retires over the [`inject job`](#failed-injection-saved-retry) cadence.
 
+#### Ensemble or "Torrent Aggregation"
+
+:::danger
+This is an upcoming feature for v6.
+:::
+
+Many of you may be familiar with things like [seasonpackarr](https://github.com/nuxencs/seasonpackarr) which will aggregate/join your already downloaded episodes into season packs when they are combined and uploaded on your trackers, and inject them. `cross-seed` can now do the same, linking and then creating a "combined" set of matching torrents or data to get you seeding data you already have faster. Currently, only season packs from individual episodes is supported but we may support additional aggregation in the future.
+
+This functionality for season packs is linked to the new option [seasonFromEpisodes](./basics/options.md#seasonFromEpisodes) - which is a ratio of episodes you need to have for a match.
+
+:::tip
+This feature works best with [partial matching](#partial-matching) and [Sonarr](./basics/options.md#sonarr). You can avoid downloading the same missing episodes on multiple trackers by following [these steps](./basics/faq-troubleshooting.md#my-partial-matches-from-related-searches-are-missing-the-same-data-how-can-i-only-download-it-once).
+:::
+
 #### Sonarr TV Library Searching
 
 We always recommend, whenever possible, to feed original un-renamed data files or (preferably) .torrent files (using `torrentDir`) into cross-seed for searching. However, certain cases, primarily Usenet season pack downloads, could be searched using [data-matching](./tutorials/data-based-matching.md) from a Sonarr TV Library but would not always perform searches "properly" due to the nested folder structures and lack of risky matching supporting multi-file searches.