From 4298db7546d3f9722fc136351f1aa5e6eee967da Mon Sep 17 00:00:00 2001 From: rlaphoenix <17136956+rlaphoenix@users.noreply.github.com> Date: Mon, 27 Oct 2025 13:07:31 +0000 Subject: [PATCH] Improve Installation/Usage in README, update badges for uv --- README.md | 129 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 92 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 23ee5d6..e9d2842 100644 --- a/README.md +++ b/README.md @@ -5,17 +5,20 @@

- - Build status + + License Python version + + Manager: uv + Linter: Ruff - - Dependency management: Poetry + + Build status

@@ -32,22 +35,31 @@ ## Installation -```shell -$ pip install pywidevine -``` +### With pip -> **Note** -If pip gives you a warning about a path not being in your PATH environment variable then promptly add that path then -close all open command prompt/terminal windows, or `pywidevine` CLI won't work as it will not be found. +> Since *pip* is pre-installed with Python, it is the most straight forward way to install pywidevine. -Voilà 🎉 — You now have the `pywidevine` package installed! -You can now import pywidevine in scripts ([see below](#usage)). -A command-line interface is also available, try `pywidevine --help`. +Simply run `pip install pywidevine` and it will be ready to use from the CLI or within scripts in a minute. + +### With uv + +> This is recommended for those who wish to install from the source code, are working on changes in the source code, or +just simply prefer it's many handy features. + +Go to to the official website and [get uv installed](https://docs.astral.sh/uv/getting-started/installation/). Download +or clone this repository, go inside it, and run `uv run pywidevine --version`. To run scripts, like a `license.py` that +is importing pywidevine, do `uv run license.py`. Effectively, put `uv run` before calling whatever is using pywidevine. +For other ways to run pywidevine with uv, see [Running commands](https://docs.astral.sh/uv/guides/projects/#running-commands). ## Usage -The following is a minimal example of using pywidevine in a script to get a License for Bitmovin's -Art of Motion Demo. +There are two ways to use pywidevine, through scripts, or the CLI (command-line interface). +Most people would be using it through scripts due to complexities working with license server APIs. + +### Scripts + +The following is a minimal example of using pywidevine in a script to get a License for Bitmovin's Art of Motion Demo. +This demo can be found on [Bitmovin's DRM Stream Test demo page](https://bitmovin.com/demos/drm/). ```py from pywidevine.cdm import Cdm @@ -56,50 +68,93 @@ from pywidevine.pssh import PSSH import requests -# prepare pssh +# prepare pssh (usually inside the MPD/M3U8, an API response, the player page, or inside the pssh mp4 box) pssh = PSSH("AAAAW3Bzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAADsIARIQ62dqu8s0Xpa" "7z2FmMPGj2hoNd2lkZXZpbmVfdGVzdCIQZmtqM2xqYVNkZmFsa3IzaioCSEQyAA==") -# load device +# load device from a WVD file (your provision) device = Device.load("C:/Path/To/A/Provision.wvd") -# load cdm +# load cdm (creating a CDM instance using that device) cdm = Cdm.from_device(device) -# open cdm session +# open cdm session (note that any one device should have a practical limit to amount of sessions open at any one time) session_id = cdm.open() -# get license challenge +# get license challenge (generate a license request message, signed using the device with the pssh) challenge = cdm.get_license_challenge(session_id, pssh) -# send license challenge (assuming a generic license server SDK with no API front) -licence = requests.post("https://...", data=challenge) +# send license challenge to bitmovin's license server (which has no auth and asks simply for the license challenge as-is) +# another license server may require authentication and ask for it as JSON or form data instead +# you may also be required to use privacy mode, where you use their service certificate when creating the challenge +licence = requests.post("https://cwip-shaka-proxy.appspot.com/no_auth", data=challenge) licence.raise_for_status() -# parse license challenge +# parse the license response message received from the license server API cdm.parse_license(session_id, licence.content) # print keys for key in cdm.get_keys(session_id): print(f"[{key.type}] {key.kid.hex}:{key.key.hex()}") -# close session, disposes of session data +# finished, close the session, disposing of all keys and other related data cdm.close(session_id) ``` -> **Note** -> There are various features not shown in this specific example like: -> -> - Privacy Mode -> - Setting Service Certificates -> - Remote CDMs and Serving -> - Choosing a License Type to request -> - Creating WVD files -> - and much more! -> -> Take a look at the methods available in the [Cdm class](/pywidevine/cdm.py) and their doc-strings for -> further information. For more examples see the [CLI functions](/pywidevine/main.py) which uses a lot -> of previously mentioned features. +There are other features not shown in this small example like: + +- Privacy Mode +- Setting Service Certificates +- Remote CDMs and Serving +- Choosing a License Type +- Creating WVD files +- and much more! + +> [!TIP] +> For examples, take a look at the methods available in the [Cdm class](/pywidevine/cdm.py) and read their doc-strings +> for further information. + +### Command-line Interface + +The CLI can be useful to do simple license calls, migrate WVD files, and test provisions. +Take a look at `pywidevine --help` to see a list of commands available. + +```plain +Usage: pywidevine [OPTIONS] COMMAND [ARGS]... + + pywidevine—Python Widevine CDM implementation. + +Options: + -v, --version Print version information. + -d, --debug Enable DEBUG level logs. + --help Show this message and exit. + +Commands: + create-device Create a Widevine Device (.wvd) file from an RSA Private... + export-device Export a Widevine Device (.wvd) file to an RSA Private... + license Make a License Request for PSSH to SERVER using DEVICE. + migrate Upgrade from earlier versions of the Widevine Device... + serve Serve your local CDM and Widevine Devices Remotely. + test Test the CDM code by getting Content Keys for Bitmovin's... +``` + +Every command has further help information, simply type `pywidevine --help`. +For example, `pywidevine test --help`: + +```plain +Usage: pywidevine test [OPTIONS] DEVICE + + Test the CDM code by getting Content Keys for Bitmovin's Art of Motion + example. https://bitmovin.com/demos/drm + https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd + + The device argument is a Path to a Widevine Device (.wvd) file which + contains the device private key among other required information. + +Options: + -p, --privacy Use Privacy Mode, off by default. + --help Show this message and exit. +``` ## Disclaimer