Skip to main content

A library to interact with the Xbox One gaming console via the SmartGlass protocol.

Project description


PyPi version Docs Build status Discord chat

This library provides the core foundation for the smartglass protocol that is used with the Xbox One Gaming console

For in-depth information, check out the documentation:

NOTE: Since 29.02.2020 the following modules are integrated into core: stump, auxiliary, rest-server NOTE: Nano module is still offered seperately


  • Power on / off the console
  • Get system info (running App/Game/Title, dashboard version)
  • Media player control (seeing content id, content app, playback actions etc.)
  • Stump protocol (Live-TV Streaming / IR control)
  • Title / Auxiliary stream protocol (f.e. Fallout 4 companion app)
  • Trigger GameDVR remotely
  • REST Server

Major frameworks used


Via pip

pip install xbox-smartglass-core

See the end of this README for development-targeted instructions.

How to use

There are several command line utilities to check out::


Some functionality, such as GameDVR record, requires authentication with your Microsoft Account to validate you have the right to trigger such action.

To authenticate / get authentication tokens use::


REST server

Start the server daemon

Usage information

Example localhost:

# Serve on ''
$ xbox-rest-server
INFO:     Started server process [927195]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on (Press CTRL+C to quit)

Example local network: is the IP address of your computer running the server:

xbox-rest-server --host -p 1234
INFO:     Started server process [927195]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on (Press CTRL+C to quit)


Since the migration from Flask framework to FastAPI, there is a nice OpenAPI documentation available:



If your server runs on something else than or you need to register your own OAUTH application on Azure AD and supply appropriate parameters to the login-endpoint of the REST server.

Check out:

Fallout 4 relay service

To forward the title communication from the Xbox to your local host to use third-party Fallout 4 Pip boy applications or extensions



Here you can see the SmartGlass TUI (Text user interface):

TUI list TUI console TUI log TUI log detail

Development workflow

Ready to contribute? Here's how to set up xbox-smartglass-core-python for local development.

  1. Fork the xbox-smartglass-core-python repo on GitHub.
  2. Clone your fork locally
git clone
  1. Install your local copy into a virtual environment. This is how you set up your fork for local development
python -m venv ~/pyvenv/xbox-smartglass
source ~/pyvenv/xbox-smartglass/bin/activate
cd xbox-smartglass-core-python
pip install -e .[dev]
  1. Create a branch for local development::
git checkout -b name-of-your-bugfix-or-feature
  1. Make your changes.

  2. Before pushing the changes to git, please verify they actually work

  1. Commit your changes and push your branch to GitHub::
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
  1. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. Code includes unit-tests.
  2. Added code is properly named and documented.
  3. On major changes the README is updated.
  4. Run tests / linting locally before pushing to remote.


Kudos to joelday for figuring out the AuxiliaryStream / TitleChannel communication first! You can find the original implementation here: SmartGlass.CSharp

This package uses parts of Cookiecutter and the audreyr/cookiecutter-pypackage project template


1.3.0 (2020-11-02)

  • Drop Python 3.6 support
  • Deprecate Authentication via TUI
  • Major rewrite (Migration from gevent -> asyncio)
  • Rewrite of REST Server (Migration FLASK -> FastAPI)
  • Adjust to xbox-webapi-python v2.0.8
  • New OAUTH login flow

1.2.2 (2020-04-03)

  • Fix: Assign tokenfile path to flask_app (aka. REST server instance)

1.2.1 (2020-03-04)

  • cli: Python3.6 compatibility change
  • HOTFIX: Add xbox.handlers to packages in

1.2.0 (2020-03-04)

  • CLI scripts rewritten, supporting log/loglevel args now, main script is called xbox-cli now
  • Add REPL / REPL server functionality
  • Updates to README and REST server documentation

1.1.2 (2020-02-29)

  • Drop support for Python 3.5
  • crypto: Fix deprecated cryptography functions
  • tests: Speed up REST server tests (discovery, poweron)
  • Update all dependencies

1.1.1 (2020-02-29)

  • FIX: Include static files for REST server in distributable package
  • REST: Remove deprecated packages from showing in /versions endpoint

1.1.0 (2020-02-29)

  • Clean up dependencies
  • Merge in xbox-smartglass-rest, deprecate standalone package
  • Merge in xbox-smartglass-stump, deprecate standalone package
  • Merge in xbox-smartglass-auxiliary, deprecate standalone package
  • tui: Fix crash when bringing up command menu, support ESC to exit

1.0.12 (2018-11-14)

  • Python 3.7 compatibility

1.0.11 (2018-11-05)

  • Add game_dvr_record to Console-class
  • Fix PCAP parser
  • Add last_error property to Console-class

1.0.10 (2018-08-14)

  • Safeguard around connect() functions, if userhash and xsts_token is NoneType

1.0.9 (2018-08-11)

  • Fix for Console instance poweron
  • Reset state after poweroff
  • Little fixes to TUI
  • Support handling MessageFragments

1.0.8 (2018-06-14)

  • Use aenum library for backwards-compat with enum.Flag on py3.5

1.0.7 (2018-05-16)

  • CoreProtocol.connect: Treat ConnectionResult.Pending as error
  • constants.WindowsClientInfo: Update ClientVersion 15 -> 39
  • Make CoreProtocol.start_channel take optional title_id / activity_id arguments

1.0.1 (2018-05-03)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xbox-smartglass-core-1.3.0.tar.gz (395.5 kB view hashes)

Uploaded source

Built Distribution

xbox_smartglass_core-1.3.0-py2.py3-none-any.whl (85.7 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page