Download Files
dl.download is one function that handles four cases. It looks at the kind of the resolved node and picks the right strategy.
A single file by path
Inside a Prefix context:
Or with an absolute path, no context needed:
If to= ends with a / or is an existing directory, the file lands inside it with its original filename. Otherwise to= is the exact output path.
A whole folder, recursive
Pass a folder path — dl.download recognizes the kind is folder (not a file) and streams every descendant leaf, preserving relative paths:
Result:
An entire episode
Same function, pass the episode path:
Every file across every sub-folder of the episode is downloaded with its full structure under to=.
By node ID
If you already have an ID (from a previous dl.upload response, a lookup_node call, or the preview UI), pass it directly. The SDK detects a 24-char hex string and skips path resolution:
Works for any kind — files, folders, episodes.
A whole bindr
Bindrs need a separate function because they can mix files and folders from anywhere:
Each member becomes a top-level entry under to=. Folder members keep their internal structure; file members land directly.
Best practices
- Pick
to=for the unit you're pulling. A single file → use a filename or directory. A folder → use a directory. The SDK createsto=if it doesn't exist. - Don't pre-flatten with absolute paths in your code. Let the SDK rebuild the tree under
to=— that way the output mirrors what's in DreamLake. - Bytes flow direct from S3. The download URL is presigned and short-lived; the bytes never traverse the BSS server. This means big files don't compete for server bandwidth.
- Resume isn't built into the high-level API yet. If a multi-gigabyte folder download is interrupted, re-run — already-downloaded files are overwritten cheaply, but partial files restart from zero.
What you can do next
- Bindrs — curate exactly what you want to download
- Upload an Episode — get data in so you have something to pull back