pychromecast |Build Status|
===========================
.. |Build Status| image:: https://travis-ci.org/balloob/pychromecast.svg?branch=master
:target: https://travis-ci.org/balloob/pychromecast
Library for Python 3.11+ to communicate with the Google Chromecast. It
currently supports:
- Auto discovering connected Chromecasts on the network
- Start the default media receiver and play any online media
- Control playback of current playing media
- Implement Google Chromecast api v2
- Communicate with apps via channels
- Easily extendable to add support for unsupported namespaces
- Multi-room setups with Audio cast devices
*Check out* `Home Assistant <https://home-assistant.io>`_ *for a
ready-made solution using PyChromecast for controlling and automating
your Chromecast or Cast-enabled device like Google Home.*
Dependencies
------------
PyChromecast depends on the Python packages requests, protobuf and
zeroconf. Make sure you have these dependencies installed using
``pip install -r requirements.txt``
How to use
----------
.. code:: python
>> import time
>> import pychromecast
>> import zeroconf
>> # Create a browser which prints the friendly name of found chromecast devices
>> zconf = zeroconf.Zeroconf()
>> browser = pychromecast.CastBrowser(pychromecast.SimpleCastListener(lambda uuid, service: print(browser.devices[uuid].friendly_name)), zconf)
>> browser.start_discovery()
>> # Shut down discovery
>> pychromecast.discovery.stop_discovery(browser)
>> # Discover and connect to chromecasts named Living Room
>> chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=["Living Room"])
>> [cc.cast_info.friendly_name for cc in chromecasts]
['Living Room']
>> # Discover and connect to more than one device
>> chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=["Living Room","Bed Room","Kitchen"])
>> [cc.device.friendly_name for cc in chromecasts]
["Living Room","Bed Room","Kitchen"]
>> # If you are seeing less devices get discovered than expected add the below parameter. You can lessen or extend the timeout as needed.
>> chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=["Living Room","Bed Room","Kitchen"],discovery_timeout=30)
>> [cc.device.friendly_name for cc in chromecasts]
["Living Room","Bed Room","Kitchen"]
>> cast = chromecasts[0]
>> # Start worker thread and wait for cast device to be ready
>> cast.wait()
>> print(cast.cast_info)
CastInfo(services={ServiceInfo(type='mdns', data='Chromecast-Audio-42feced1d94238232fba92623e2682f3._googlecast._tcp.local.')}, uuid=UUID('42feced1-d942-3823-2fba-92623e2682f3'), model_name='Chromecast Audio', friendly_name='Living room', host='192.168.0.189', port=8009, cast_type='audio', manufacturer='Google Inc.')
>> print(cast.status)
CastStatus(is_active_input=True, is_stand_by=False, volume_level=1.0, volume_muted=False, app_id='CC1AD845', display_name='Default Media Receiver', namespaces=['urn:x-cast:com.google.cast.player.message', 'urn:x-cast:com.google.cast.media'], session_id='CCA39713-9A4F-34A6-A8BF-5D97BE7ECA5C', transport_id='web-9', status_text='')
>> mc = cast.media_controller
>> mc.play_media('http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4', 'video/mp4')
>> mc.block_until_active()
>> print(mc.status)
MediaStatus(current_time=42.458322, content_id='http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4', content_type='video/mp4', duration=596.474195, stream_type='BUFFERED', idle_reason=None, media_session_id=1, playback_rate=1, player_state='PLAYING', supported_media_commands=15, volume_level=1, volume_muted=False)
>> mc.pause()
>> time.sleep(5)
>> mc.play()
>> # Shut down discovery
>> pychromecast.discovery.stop_discovery(browser)
Adding support for extra namespaces
-----------------------------------
Each app that runs on the Chromecast supports namespaces. They specify a
JSON-based mini-protocol. This is used to communicate between the
Chromecast and your phone/browser and now Python.
Support for extra namespaces is added by using controllers. To add your own namespace to a current chromecast instance you will first have to define your controller. Example of a minimal controller:
.. code:: python
from pychromecast.controllers import BaseController
class MyController(BaseController):
def __init__(self):
super(MyController, self).__init__(
"urn:x-cast:my.super.awesome.namespace")
def receive_message(self, message, data):
print("Wow, I received this message: {}".format(data))
return True # indicate you handled this message
def request_beer(self):
self.send_message({'request': 'beer'})
After you have defined your controller you will have to add an instance to a Chromecast object: `cast.register_handler(MyController())`. When a message is received with your namespace it will be routed to your controller.
For more options see the `BaseController`_. For an example of a fully implemented controller see the `MediaController`_.
.. _BaseController: https://github.com/balloob/pychromecast/blob/master/pychromecast/controllers/__init__.py
.. _MediaController: https://github.com/balloob/pychromecast/blob/master/pychromecast/controllers/media.py
Exploring existing namespaces
-------------------------------
So you've got PyChromecast running and decided it is time to add support to your favorite app. No worries, the following instructions will have you covered in exploring the possibilities.
The following instructions require the use of the `Google Chrome browser`_ and the `Google Cast plugin`_.
* In Chrome, go to `chrome://net-export/`
* Select 'Include raw bytes (will include cookies and credentials)'
* Click 'Start Logging to Disk'
* Open a new tab, browse to your favorite application on the web that has Chromecast support and start casting.
* Go back to the tab that is capturing events and click on stop.
* Open https://netlog-viewer.appspot.com/ and select your event log file.
* Browse to https://netlog-viewer.appspot.com/#events&q=type:SOCKET, and find the socket that has familiar JSON data. (For me, it's usually the second or third from the top.)
* Go through the results and collect the JSON that is exchanged.
* Now write a controller that is able to mimic this behavior :-)
.. _Google Chrome Browser: https://www.google.com/chrome/
.. _Google Cast Plugin: https://chrome.google.com/webstore/detail/google-cast/boadgeojelhgndaghljhdicfkmllpafd
Ignoring CEC Data
-----------------
The Chromecast typically reports whether it is the active input on the device
to which it is connected. This value is stored inside a cast object in the
following property.
.. code:: python
cast.status.is_active_input
Some Chromecast users have reported CEC incompatibilities with their media
center devices. These incompatibilities may sometimes cause this active input
value to be reported improperly.
This active input value is typically used to determine if the Chromecast
is idle. PyChromecast is capable of ignoring the active input value when
determining if the Chromecast is idle in the instance that the
Chromecast is returning erroneous values. To ignore this CEC detection
data in PyChromecast, append a `Linux style wildcard`_ formatted string
to the IGNORE\_CEC list in PyChromecast like in the example below.
.. code:: python
pychromecast.IGNORE_CEC.append('*') # Ignore CEC on all devices
pychromecast.IGNORE_CEC.append('Living Room') # Ignore CEC on Chromecasts named Living Room
Networking requirements
-----------------------
Pychromecast relies on mDNS to discover cast devices. The mDNS protocol relies on multicast UDP on port 5353 which comes with several implications for discovery to work:
- Multicast UDP must be forwarded by WiFI routers; some WiFi routers are known to drop multicast UDP traffic.
- The device running pychromecast must allow both inbound and outbound traffic on port 5353.
- The device running pychromecast must be on the same subnet as the cast devices because mDNS packets are not routed across subnets.
If not all of these conditions are met, discovery will not work. In cases where these conditions are impossible to meet, it's possible to pass a list of known IP-addresses or host names to the discovery functions.
Thanks
------
I would like to thank `Fred Clift`_ for laying the socket client ground
work. Without him it would not have been possible!
.. _Linux style wildcard: http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm
.. _Fred Clift: https://github.com/minektur
|ohf-logo|
.. |ohf-logo| image:: https://www.openhomefoundation.org/badges/pychromecast.png
:alt: PyChromecast - A library from the Open Home Foundation
:target: https://www.openhomefoundation.org/
Raw data
{
"_id": null,
"home_page": null,
"name": "PyChromecast",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11.0",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Paulus Schoutsen <paulus@paulusschoutsen.nl>",
"download_url": "https://files.pythonhosted.org/packages/a2/21/9c1ba37839a605dd048b3b7d6d36162562f89f86f4bfa248a7b0655551fd/PyChromecast-14.0.5.tar.gz",
"platform": "any",
"description": "pychromecast |Build Status|\n===========================\n\n.. |Build Status| image:: https://travis-ci.org/balloob/pychromecast.svg?branch=master\n :target: https://travis-ci.org/balloob/pychromecast\n\nLibrary for Python 3.11+ to communicate with the Google Chromecast. It\ncurrently supports:\n\n- Auto discovering connected Chromecasts on the network\n- Start the default media receiver and play any online media\n- Control playback of current playing media\n- Implement Google Chromecast api v2\n- Communicate with apps via channels\n- Easily extendable to add support for unsupported namespaces\n- Multi-room setups with Audio cast devices\n\n*Check out* `Home Assistant <https://home-assistant.io>`_ *for a\nready-made solution using PyChromecast for controlling and automating\nyour Chromecast or Cast-enabled device like Google Home.*\n\nDependencies\n------------\n\nPyChromecast depends on the Python packages requests, protobuf and\nzeroconf. Make sure you have these dependencies installed using\n``pip install -r requirements.txt``\n\nHow to use\n----------\n\n.. code:: python\n\n >> import time\n >> import pychromecast\n >> import zeroconf\n\n >> # Create a browser which prints the friendly name of found chromecast devices\n >> zconf = zeroconf.Zeroconf()\n >> browser = pychromecast.CastBrowser(pychromecast.SimpleCastListener(lambda uuid, service: print(browser.devices[uuid].friendly_name)), zconf)\n >> browser.start_discovery()\n >> # Shut down discovery\n >> pychromecast.discovery.stop_discovery(browser)\n\n >> # Discover and connect to chromecasts named Living Room\n >> chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=[\"Living Room\"])\n >> [cc.cast_info.friendly_name for cc in chromecasts]\n ['Living Room']\n\n >> # Discover and connect to more than one device\n >> chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=[\"Living Room\",\"Bed Room\",\"Kitchen\"])\n >> [cc.device.friendly_name for cc in chromecasts]\n [\"Living Room\",\"Bed Room\",\"Kitchen\"]\n \n >> # If you are seeing less devices get discovered than expected add the below parameter. You can lessen or extend the timeout as needed.\n >> chromecasts, browser = pychromecast.get_listed_chromecasts(friendly_names=[\"Living Room\",\"Bed Room\",\"Kitchen\"],discovery_timeout=30)\n >> [cc.device.friendly_name for cc in chromecasts]\n [\"Living Room\",\"Bed Room\",\"Kitchen\"]\n\n >> cast = chromecasts[0]\n >> # Start worker thread and wait for cast device to be ready\n >> cast.wait()\n >> print(cast.cast_info)\n CastInfo(services={ServiceInfo(type='mdns', data='Chromecast-Audio-42feced1d94238232fba92623e2682f3._googlecast._tcp.local.')}, uuid=UUID('42feced1-d942-3823-2fba-92623e2682f3'), model_name='Chromecast Audio', friendly_name='Living room', host='192.168.0.189', port=8009, cast_type='audio', manufacturer='Google Inc.')\n\n >> print(cast.status)\n CastStatus(is_active_input=True, is_stand_by=False, volume_level=1.0, volume_muted=False, app_id='CC1AD845', display_name='Default Media Receiver', namespaces=['urn:x-cast:com.google.cast.player.message', 'urn:x-cast:com.google.cast.media'], session_id='CCA39713-9A4F-34A6-A8BF-5D97BE7ECA5C', transport_id='web-9', status_text='')\n\n >> mc = cast.media_controller\n >> mc.play_media('http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4', 'video/mp4')\n >> mc.block_until_active()\n >> print(mc.status)\n MediaStatus(current_time=42.458322, content_id='http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4', content_type='video/mp4', duration=596.474195, stream_type='BUFFERED', idle_reason=None, media_session_id=1, playback_rate=1, player_state='PLAYING', supported_media_commands=15, volume_level=1, volume_muted=False)\n\n >> mc.pause()\n >> time.sleep(5)\n >> mc.play()\n\n >> # Shut down discovery\n >> pychromecast.discovery.stop_discovery(browser)\n\nAdding support for extra namespaces\n-----------------------------------\n\nEach app that runs on the Chromecast supports namespaces. They specify a\nJSON-based mini-protocol. This is used to communicate between the\nChromecast and your phone/browser and now Python.\n\nSupport for extra namespaces is added by using controllers. To add your own namespace to a current chromecast instance you will first have to define your controller. Example of a minimal controller:\n\n.. code:: python\n\n from pychromecast.controllers import BaseController\n\n class MyController(BaseController):\n def __init__(self):\n super(MyController, self).__init__(\n \"urn:x-cast:my.super.awesome.namespace\")\n\n def receive_message(self, message, data):\n print(\"Wow, I received this message: {}\".format(data))\n\n return True # indicate you handled this message\n\n def request_beer(self):\n self.send_message({'request': 'beer'})\n\nAfter you have defined your controller you will have to add an instance to a Chromecast object: `cast.register_handler(MyController())`. When a message is received with your namespace it will be routed to your controller.\n\nFor more options see the `BaseController`_. For an example of a fully implemented controller see the `MediaController`_.\n\n.. _BaseController: https://github.com/balloob/pychromecast/blob/master/pychromecast/controllers/__init__.py\n.. _MediaController: https://github.com/balloob/pychromecast/blob/master/pychromecast/controllers/media.py\n\nExploring existing namespaces\n-------------------------------\nSo you've got PyChromecast running and decided it is time to add support to your favorite app. No worries, the following instructions will have you covered in exploring the possibilities.\n\nThe following instructions require the use of the `Google Chrome browser`_ and the `Google Cast plugin`_.\n\n * In Chrome, go to `chrome://net-export/`\n * Select 'Include raw bytes (will include cookies and credentials)'\n * Click 'Start Logging to Disk'\n * Open a new tab, browse to your favorite application on the web that has Chromecast support and start casting.\n * Go back to the tab that is capturing events and click on stop.\n * Open https://netlog-viewer.appspot.com/ and select your event log file.\n * Browse to https://netlog-viewer.appspot.com/#events&q=type:SOCKET, and find the socket that has familiar JSON data. (For me, it's usually the second or third from the top.)\n * Go through the results and collect the JSON that is exchanged.\n * Now write a controller that is able to mimic this behavior :-)\n\n.. _Google Chrome Browser: https://www.google.com/chrome/\n.. _Google Cast Plugin: https://chrome.google.com/webstore/detail/google-cast/boadgeojelhgndaghljhdicfkmllpafd\n\nIgnoring CEC Data\n-----------------\nThe Chromecast typically reports whether it is the active input on the device\nto which it is connected. This value is stored inside a cast object in the\nfollowing property.\n\n.. code:: python\n\n cast.status.is_active_input\n\nSome Chromecast users have reported CEC incompatibilities with their media\ncenter devices. These incompatibilities may sometimes cause this active input\nvalue to be reported improperly.\n\nThis active input value is typically used to determine if the Chromecast\nis idle. PyChromecast is capable of ignoring the active input value when\ndetermining if the Chromecast is idle in the instance that the\nChromecast is returning erroneous values. To ignore this CEC detection\ndata in PyChromecast, append a `Linux style wildcard`_ formatted string\nto the IGNORE\\_CEC list in PyChromecast like in the example below.\n\n.. code:: python\n\n pychromecast.IGNORE_CEC.append('*') # Ignore CEC on all devices\n pychromecast.IGNORE_CEC.append('Living Room') # Ignore CEC on Chromecasts named Living Room\n\nNetworking requirements\n-----------------------\nPychromecast relies on mDNS to discover cast devices. The mDNS protocol relies on multicast UDP on port 5353 which comes with several implications for discovery to work:\n\n- Multicast UDP must be forwarded by WiFI routers; some WiFi routers are known to drop multicast UDP traffic.\n- The device running pychromecast must allow both inbound and outbound traffic on port 5353.\n- The device running pychromecast must be on the same subnet as the cast devices because mDNS packets are not routed across subnets.\n\nIf not all of these conditions are met, discovery will not work. In cases where these conditions are impossible to meet, it's possible to pass a list of known IP-addresses or host names to the discovery functions.\n\nThanks\n------\n\nI would like to thank `Fred Clift`_ for laying the socket client ground\nwork. Without him it would not have been possible!\n\n.. _Linux style wildcard: http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm\n.. _Fred Clift: https://github.com/minektur\n\n|ohf-logo|\n\n.. |ohf-logo| image:: https://www.openhomefoundation.org/badges/pychromecast.png\n :alt: PyChromecast - A library from the Open Home Foundation\n :target: https://www.openhomefoundation.org/\n",
"bugtrack_url": null,
"license": null,
"summary": "Python module to talk to Google Chromecast.",
"version": "14.0.5",
"project_urls": {
"Homepage": "https://github.com/home-assistant-libs/pychromecast"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "060aff82969e5ea0dfff5bd00bac505114bb356f64b309c502d39b26c9dc525b",
"md5": "efeb62c8d3814ceec250fbd3f3a3eb57",
"sha256": "f1ec3858e4659422f0afbd37775f26551a6fc2d66f18a7bc44d66c0b1f59fc97"
},
"downloads": -1,
"filename": "PyChromecast-14.0.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "efeb62c8d3814ceec250fbd3f3a3eb57",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.11.0",
"size": 76650,
"upload_time": "2024-10-27T07:53:58",
"upload_time_iso_8601": "2024-10-27T07:53:58.507934Z",
"url": "https://files.pythonhosted.org/packages/06/0a/ff82969e5ea0dfff5bd00bac505114bb356f64b309c502d39b26c9dc525b/PyChromecast-14.0.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a2219c1ba37839a605dd048b3b7d6d36162562f89f86f4bfa248a7b0655551fd",
"md5": "23f52c2a7f1ad5e3c5759d74d42b4a46",
"sha256": "a8671ee4ea4a7095e2e0670e2215145ec1e3e0aa0737ff74d648ae4dc268b2b1"
},
"downloads": -1,
"filename": "PyChromecast-14.0.5.tar.gz",
"has_sig": false,
"md5_digest": "23f52c2a7f1ad5e3c5759d74d42b4a46",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11.0",
"size": 60934,
"upload_time": "2024-10-27T07:54:00",
"upload_time_iso_8601": "2024-10-27T07:54:00.596317Z",
"url": "https://files.pythonhosted.org/packages/a2/21/9c1ba37839a605dd048b3b7d6d36162562f89f86f4bfa248a7b0655551fd/PyChromecast-14.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-27 07:54:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "home-assistant-libs",
"github_project": "pychromecast",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "casttube",
"specs": [
[
"==",
"0.2.1"
]
]
},
{
"name": "protobuf",
"specs": [
[
"==",
"5.28.2"
]
]
},
{
"name": "zeroconf",
"specs": [
[
"==",
"0.135.0"
]
]
}
],
"lcname": "pychromecast"
}
JSON
