diff --git a/Download-Types.md b/Download-Types.md index e60e3b9..255241c 100644 --- a/Download-Types.md +++ b/Download-Types.md @@ -1,27 +1,45 @@ -## Download Type Details +# 📥 Repertory Download Types -`repertory` supports 3 different modes for reading and writing files: `default`, `direct`, and `ring_buffer`. +Repertory supports **three modes** for reading and writing files: +`default`, `direct`, and `ring_buffer`. -The `PreferredDownloadType` setting in `config.json` determines which of these modes is preferred. This does not guarantee the mode will always be chosen, as `repertory` will choose an appropriate mode based on the type of file operation being performed. If a file is currently open via a read-only download type and a request to write is performed, the file will automatically be changed to `default` mode without any interruptions to file i/o. +You can set your preferred mode using the `PreferredDownloadType` option in `config.json`. +> **Note:** The actual mode may switch automatically depending on the file operation. +> Example: If a file is opened read-only and a write occurs, Repertory will switch to **default** mode. -### Default +--- - * In `default` mode, a file of equal size is fully allocated within the`cache` directory. - * File i/o occurs in 8MiB chunks for files that are not currently in cache. - * Even though writes occur within 1 or more 8MiB chunks, the file will not be scheduled for upload until all chunks have been downloaded. - * If `repertory` is unmounted prior to an upload completing, it will be re-scheduled the next time the location is mounted. - * This mode will be forced if any request to write is performed. - * This mode is read/write. +## 🔹 Mode Overview -### Direct +| Mode | Description | Access Type | +|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------|-------------| +| **default** | Creates a local cache file matching the full size of the remote file. Reads/writes in 8 MiB chunks. Writes are uploaded only after full download. If the mount is unmounted prematurely, uploads resume on the next mount. | Read/Write | +| **direct** | Reads directly from the provider without creating a local cache file. Uses an **in-memory ring buffer** (up to five 8 MiB chunks). | Read-only | +| **ring_buffer** | Allocates a **fixed-size buffer file** (default 512 MiB) inside the `buffer` directory. Used for reading large files that exceed the ring buffer size. | Read-only | - * In `direct` mode, files are read directly from the corresponding provider without any local caching. - * An in-memory ring buffer is used to cache up to 5 8MiB chunks. - * This mode is read-only. - -### Ring buffer +--- - * In `ring_buffer` mode, a fixed-size file (default 512MiB) is allocated within the `buffer` directory. - * This mode will cache up to 512MiB of a file locally preventing the need to fully allocate a file for read operations. - * This mode is only chosen when the actual file size is greater than the ring-buffer size. - * This mode is read-only. \ No newline at end of file +## 🛠 Choosing the Right Mode + +- **Use `default`** when: + - You need both read and write access. + - You want to ensure files can upload after partial downloads or disconnections. +- **Use `direct`** when: + - You only need read access. + - You want the lowest disk usage. + - You’re streaming smaller files and have sufficient RAM for the buffer. +- **Use `ring_buffer`** when: + - You are reading very large files repeatedly. + - You want to limit memory usage by using a fixed-size disk buffer. + +--- + +## ⚙️ Example Config + +```json +{ + "PreferredDownloadType": "default" +} +``` + +Replace `"default"` with `"direct"` or `"ring_buffer"` to change the mode.