Metadata-Version: 2.5
Name: sharepoint-dl
Version: 1.2.0
Summary: Download videos and files from SharePoint — like yt-dlp for SharePoint
Project-URL: Homepage, https://github.com/bhayanak/sp-dl
Project-URL: Repository, https://github.com/bhayanak/sp-dl
Project-URL: Issues, https://github.com/bhayanak/sp-dl/issues
License: MIT
License-File: LICENSE
Keywords: download,microsoft,sharepoint,stream,video
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: lxml>=5.0
Requires-Dist: msal>=1.28
Requires-Dist: playwright>=1.45
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# sharepoint-dl

<p align="center">
  <img src="assets/logo.svg" alt="sharepoint-dl logo" width="128" height="128">
</p>

<p align="center">
  <strong>Download videos and files from SharePoint — like yt-dlp for SharePoint.</strong>
</p>

<p align="center">
  <a href="https://github.com/bhayanak/sp-dl/actions/workflows/ci.yml"><img src="https://github.com/bhayanak/sp-dl/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/bhayanak/sp-dl"><img src="https://codecov.io/gh/bhayanak/sp-dl/graph/badge.svg" alt="Coverage"></a>
  <a href="https://pypi.org/project/sharepoint-dl/"><img src="https://img.shields.io/pypi/v/sharepoint-dl" alt="PyPI"></a>
  <a href="https://pypi.org/project/sharepoint-dl/"><img src="https://img.shields.io/pypi/pyversions/sharepoint-dl" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
</p>

---

## Why?

- Microsoft Stream (Classic) was retired — all videos now live in **SharePoint / OneDrive**
- Browser downloads fail for large files, offer no resume, and require clicking through menus
- **Enterprise tenants often block direct downloads** — `sp-dl` handles this automatically via adaptive streaming
- **yt-dlp** doesn't support SharePoint authentication
- `sp-dl` gives you **one command** to download any file from SharePoint

## What It Downloads

| Content | Source |
|---|---|
| Videos (.mp4, .mov, .webm) | SharePoint document libraries, Stream on SharePoint |
| Meeting recordings | OneDrive / SharePoint auto-saved recordings |
| Download-blocked videos | Enterprise tenants with admin download restrictions |
| Any file | SharePoint document libraries |
| Shared links | Anonymous or org-internal sharing links |

## Install

```bash
pip install sharepoint-dl
```

Or with [pipx](https://pipx.pypa.io/) for isolated install:

```bash
pipx install sharepoint-dl
```

## Quick Start

**First time?** Run `sp-dl quickstart` for a step-by-step guide.

### Just paste the URL (Recommended)

```bash
sp-dl download "https://contoso-my.sharepoint.com/personal/user/_layouts/15/stream.aspx?id=..."
```

That's it. On first run a browser window opens (your installed Chrome or Edge) — sign in to
SharePoint as usual (SSO/MFA all work). `sp-dl` captures the session cookies, closes the window,
and downloads. The session is saved under `~/.config/sp-dl/` and reused for later downloads, so
you normally only sign in once.

> If neither Chrome nor Edge is installed, run `playwright install chromium` once.

### Using a Cookie File

Prefer not to let `sp-dl` open a browser? Export cookies yourself:

1. Log into SharePoint in your browser
2. Export cookies to a file using a browser extension like **"Get cookies.txt LOCALLY"**
3. Download:

```bash
sp-dl download "https://contoso.sharepoint.com/sites/Team/_layouts/15/stream.aspx?id=/sites/Team/Shared%20Documents/demo.mp4" \
  --cookies cookies.txt
```

### Headless / SSH (OAuth device code)

```bash
sp-dl download "https://contoso.sharepoint.com/sites/Team/Shared%20Documents/video.mp4" --device-code
```

### Download-Blocked Videos (Enterprise Tenants)

Some organizations disable direct file downloads via SharePoint admin policy. `sp-dl` handles this
automatically — no extra login or flags:

```bash
sp-dl download "https://contoso-my.sharepoint.com/personal/user/_layouts/15/stream.aspx?id=..."
```

**How it works:**
1. Reads the video's player metadata from the stream page (needs your SharePoint session)
2. Extracts the pre-signed media-proxy token SharePoint embeds for its own player
3. Builds a DASH manifest URL from it — no OAuth token or cookies are needed for the media proxy
4. Downloads all video/audio segments in parallel (10 concurrent connections)
5. Muxes audio + video into a single MP4 using ffmpeg

For non-blocked videos the same metadata contains a pre-signed direct download URL, which is used
as-is for maximum speed.

> **Requires** [ffmpeg](https://ffmpeg.org/download.html) for final muxing of blocked videos: `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Linux)

## Usage

```bash
# Download a video (browser sign-in on first run, then reused)
sp-dl download <URL>

# Download from a sharing link
sp-dl download "https://contoso.sharepoint.com/:v:/s/Team/EaBcDeFgHiJk"

# Show file info without downloading
sp-dl download <URL> --info

# JSON metadata
sp-dl download <URL> --json

# Custom output path
sp-dl download <URL> -o ~/Videos/meeting.mp4

# Output template
sp-dl download <URL> -o "%(site)s/%(folder)s/%(filename)s"

# Limit speed
sp-dl download <URL> --limit-rate 5M

# Skip existing files
sp-dl download <URL> --no-overwrites

# Batch download (one URL per line)
sp-dl batch urls.txt

# Use an exported cookie file instead of browser sign-in
sp-dl download <URL> -c cookies.txt

# Quick start guide
sp-dl quickstart
```

## Supported URL Patterns

| Pattern | Example |
|---|---|
| Stream player | `https://tenant.sharepoint.com/sites/Team/_layouts/15/stream.aspx?id=...` |
| Sharing link | `https://tenant.sharepoint.com/:v:/s/Team/EncodedToken` |
| Direct path | `https://tenant.sharepoint.com/sites/Team/Shared%20Documents/file.mp4` |
| OneDrive | `https://tenant-my.sharepoint.com/personal/user/Documents/file.mp4` |
| Doc.aspx | `https://tenant.sharepoint.com/sites/Team/_layouts/15/Doc.aspx?sourcedoc={guid}` |

## Authentication Methods

| Method | Best For | Setup |
|---|---|---|
| *(default)* browser sign-in | Everyone with a desktop | None — sign in once in the window that opens |
| `--cookies` | Scripted use, or if you'd rather not let sp-dl open a browser | Export cookies (e.g. "Get cookies.txt LOCALLY" extension) |
| `--device-code` | Headless servers, SSH sessions | Follow the one-time device code prompt |
| `--client-id --client-secret` | Service accounts, CI/CD | Azure AD admin setup |

> **How browser sign-in works:** `sp-dl` launches your installed Chrome/Edge (or Playwright's
> Chromium) with a dedicated profile under `~/.config/sp-dl/browser-profile`, opens the URL you
> gave it, and waits for SharePoint's `FedAuth` cookie to appear. Captured cookies are stored with
> `0600` permissions in `~/.config/sp-dl/browser-cookies/<domain>.json` and validated before each
> run; when they expire, the saved profile usually lets `sp-dl` refresh them silently in the
> background. Use `sp-dl auth logout` to wipe everything.

## Auth Management

```bash
sp-dl auth status                        # Show saved browser sessions / OAuth token state
sp-dl auth logout                        # Clear browser sessions and tokens
sp-dl auth login --tenant contoso        # Optional: OAuth device code login
sp-dl auth login --tenant contoso -i     # Optional: OAuth browser login
```

> **Tip:** You can pass a SharePoint URL as the tenant and it will be auto-detected:
> `sp-dl auth login --tenant https://contoso.sharepoint.com`

## Output Templates

| Field | Description | Example |
|---|---|---|
| `%(filename)s` | Original filename | `training.mp4` |
| `%(title)s` | Name without extension | `training` |
| `%(ext)s` | Extension | `mp4` |
| `%(site)s` | SharePoint site | `Team` |
| `%(folder)s` | Parent folder | `Recordings` |
| `%(date)s` | Modified date | `20260415` |
| `%(author)s` | Created by | `John Smith` |

## Configuration

Create `~/.config/sp-dl/config.toml`:

```toml
[defaults]
output_template = "%(filename)s"
cookies_file = "/path/to/cookies.txt"
retries = 5
no_overwrites = false

[auth]
tenant = "contoso.onmicrosoft.com"
```

Environment variables: `SP_DL_COOKIES`, `SP_DL_TENANT`, `SP_DL_CLIENT_ID`, `SP_DL_OUTPUT`

## Development

```bash
git clone https://github.com/bhayanak/sp-dl.git
cd sp-dl
pip install -e ".[dev]"

# Run tests with coverage
pytest --cov=sp_dl -v

# Lint & format
ruff check src/ tests/
ruff format src/ tests/
```

## License

[MIT](LICENSE)
