{"_id":"576d42354bcd290e00428951","category":{"_id":"576d42354bcd290e00428943","__v":0,"project":"56a526d4e7a1622b0024fae4","version":"576d42354bcd290e00428941","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-11T15:53:26.341Z","from_sync":false,"order":1,"slug":"platforms","title":"Our SDKs"},"project":"56a526d4e7a1622b0024fae4","__v":2,"user":"56a5d42ab28bc21700503989","parentDoc":null,"version":{"_id":"576d42354bcd290e00428941","project":"56a526d4e7a1622b0024fae4","__v":1,"createdAt":"2016-06-24T14:22:45.076Z","releaseDate":"2016-06-24T14:22:45.076Z","categories":["576d42354bcd290e00428942","576d42354bcd290e00428943","576d42354bcd290e00428944","576d42354bcd290e00428945","576d42354bcd290e00428946","576d42354bcd290e00428947"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-17T11:44:03.185Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"The Chirp Python SDK is designed to help with building a server-side application to send data to another device that supports receiving Chirps (iOS or Android at the moment).\n\n__This SDK is send only (i.e. it does not receive chirps).__\n\nThis SDK is distributed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Installing the Python SDK\"\n}\n[/block]\nThe current stable version of the library can be installed from the [Python Package Index](https://pypi.python.org/pypi/chirpsdk), via `pip` or `easy_install`. The latest development versioned can be downloaded from the [Chirp Admin Centre](https://admin.chirp.io). Unless you require beta features from the unstable version, we recommend using `pip`.\n\n## Dependencies\n\nFor audio I/O, the SDK relies on the host having the [Portaudio](http://www.portaudio.com/) library installed.\n\n### For Debian/Ubuntu\n\n```shell\napt-get install portaudio19-dev\n```\n\n### For OS X\n\n```shell\nbrew install portaudio\n```\n\n## Install from PyPI\n\nSimply run the following:\n\n```shell\npip install chirpsdk\n```\n\n## Install from source\n\nDownload the compressed archive from the [Chirp Admin Centre](https://admin.chirp.io). \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b571e9c-Screen_Shot_2017-01-31_at_17.04.49.png\",\n        \"Screen Shot 2017-01-31 at 17.04.49.png\",\n        359,\n        230,\n        \"#f2f2f2\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\nThen extract the archive and install the module:\n\n```shell\nunzip Chirp-Python-SDK-2.0.1.zip\ncd chirpsdk-2.0.1\npython setup.py install\n```\n\n## Test the installation\n\n```shell\npython -c \"import chirpsdk\"\n```\n\nIf this command return immediately, then the installation has been successful and you can start using it in your Python program.\n\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If the `import` command fails with an exception `ImportError: No module named chirpsdk`, the installation has not been successful. To install the Python SDK system-wide, you may need to run the installer script with root privileges:\\n\\n```\\nsudo pip install chirpsdk\\n```\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Online mode\"\n}\n[/block]\nThe online mode allows you to query our REST API in order to create or read a Chirp object. You can also get the encoded version of an identifier and vice-versa. Last but not least, you can download the Chirp sound associated with any identifier as a .wav file.\n\n## Instantiate the SDK with your credentials\n\nGet your Application's credentials from our Admin Centre and use them to instantiate a new ChirpSDK instance.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import chirpsdk\\n\\nsdk = chirpsdk.ChirpSDK('YOUR_APP_KEY', 'YOUR_APP_SECRET')\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n## Create a Chirp\n\nYou can then create a Chirp object with a dictionary, this will store the keys and values in our API and return a new identifier you can later send via the speakers.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"chirp = sdk.create_chirp({\\n    'title': 'The Godfather',\\n    'classic': True,\\n    'imdb': {\\n      'id': 'tt0068646',\\n      'rating': 9.2,\\n    },\\n  })\\nprint chirp.identifier\\n# we'll take 'ilovechirp' as an example\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nPlaying the Chirp through the speakers is as simple as\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"chirp.chirp()\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nOr if you prefer to save the Chirp sound as a .wav file\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"chirp.save_wav('/tmp/my_new_chirp.wav')\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nWithout a path, `Chirp.save_wav()` will create a file named `[identifier].wav` in the current directory, in that case `ilovechirp.wav`.\n\n## Get a Chirp\n\nNow that our new chirp has been created, we can get the data associated with it at a later time.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"another_chirp = sdk.get_chirp('ilovechirp')\\nprint another_chirp.data['title']\\n# The Godfather\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nAnd as this is also a `Chirp` object, you still have the the possibility to play the identifier on the speakers or download an audio file using the same methods as before.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Offline mode\"\n}\n[/block]\nOffline mode is not yet fully supported for the Python SDK, meaning you'll need a host connected to the Internet in order to use Chirp functionalities.\n\nHowever if you don't need to store objects online and just want to play sound or generate a large amount of .wav files we provide a way to do so without querying our API.\n\n## Play an Offline Chirp\n\nInstead of a dictionary, you can pass a string to the `Chirp.create_chirp()` method. That string needs to be a valid identifier. The created `Chirp` object will have the same methods as an Online Chirp.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"chirp = sdk.create_chirp('hitchhiker')\\nchirp.chirp()\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n  * This is especially useful if you want to use the Python SDK alongside an Offline iOS or Android application such as [Gem Swap](doc:ios-offline-walkthrough) \n\n## Save a .wav file\n\nIf you need to generate a large amount of .wav files for your application we recommend you use the built in engine instead of having to rely on an open network connection.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sdk.save_wav(chirp, offline=True)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThis will create a new file named `hitchhiker.wav`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"4. Protocols\"\n}\n[/block]\nThe Python SDK comes with our two default protocols.\nThe Standard audible one with its 10 characters long identifier from the 32 characters alphabet and the Ultrasonic inaudible one with 8 hexadecimal characters.\n\nYou can easily switch between protocols by calling the `sdk.set_protocol()` method.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sdk.set_protocol() # defaults to 'standard'\\nprint sdk.create_chirp().identifier # 'ilovechirp'\\n\\nsdk.set_protocol('ultrasonic')\\nprint sdk.create_chirp().identifier # 'df101010'\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nWhen using the Ultrasonic protocol, you might want to play the identifier on repeat. This is because ultrasounds are more sensitive to movement, direction and environment than audible sounds and thus, playing the identifier in streaming mode will ensure a higher reception ratio.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sdk.set_protocol('ultrasonic')\\nchirp = sdk.create_chirp()\\nsdk.streaming_interval = 500\\nsdk.start_streaming(chirp)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThis will play the same chirp every 0.5 seconds in a separate thread. You can close the thread and stop the loop with a call to `sdk.stop_streaming()`.\nIf you don't explicitly set an streaming interval, it will default to 1 second.","excerpt":"Using the Chirp technology to send data with Python","slug":"chirp-for-python","type":"basic","title":"Chirp for Python"}

Chirp for Python

Using the Chirp technology to send data with Python

The Chirp Python SDK is designed to help with building a server-side application to send data to another device that supports receiving Chirps (iOS or Android at the moment). __This SDK is send only (i.e. it does not receive chirps).__ This SDK is distributed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html). [block:api-header] { "type": "basic", "title": "1. Installing the Python SDK" } [/block] The current stable version of the library can be installed from the [Python Package Index](https://pypi.python.org/pypi/chirpsdk), via `pip` or `easy_install`. The latest development versioned can be downloaded from the [Chirp Admin Centre](https://admin.chirp.io). Unless you require beta features from the unstable version, we recommend using `pip`. ## Dependencies For audio I/O, the SDK relies on the host having the [Portaudio](http://www.portaudio.com/) library installed. ### For Debian/Ubuntu ```shell apt-get install portaudio19-dev ``` ### For OS X ```shell brew install portaudio ``` ## Install from PyPI Simply run the following: ```shell pip install chirpsdk ``` ## Install from source Download the compressed archive from the [Chirp Admin Centre](https://admin.chirp.io). [block:image] { "images": [ { "image": [ "https://files.readme.io/b571e9c-Screen_Shot_2017-01-31_at_17.04.49.png", "Screen Shot 2017-01-31 at 17.04.49.png", 359, 230, "#f2f2f2" ], "caption": "" } ] } [/block] Then extract the archive and install the module: ```shell unzip Chirp-Python-SDK-2.0.1.zip cd chirpsdk-2.0.1 python setup.py install ``` ## Test the installation ```shell python -c "import chirpsdk" ``` If this command return immediately, then the installation has been successful and you can start using it in your Python program. [block:callout] { "type": "warning", "body": "If the `import` command fails with an exception `ImportError: No module named chirpsdk`, the installation has not been successful. To install the Python SDK system-wide, you may need to run the installer script with root privileges:\n\n```\nsudo pip install chirpsdk\n```" } [/block] [block:api-header] { "type": "basic", "title": "2. Online mode" } [/block] The online mode allows you to query our REST API in order to create or read a Chirp object. You can also get the encoded version of an identifier and vice-versa. Last but not least, you can download the Chirp sound associated with any identifier as a .wav file. ## Instantiate the SDK with your credentials Get your Application's credentials from our Admin Centre and use them to instantiate a new ChirpSDK instance. [block:code] { "codes": [ { "code": "import chirpsdk\n\nsdk = chirpsdk.ChirpSDK('YOUR_APP_KEY', 'YOUR_APP_SECRET')", "language": "python" } ] } [/block] ## Create a Chirp You can then create a Chirp object with a dictionary, this will store the keys and values in our API and return a new identifier you can later send via the speakers. [block:code] { "codes": [ { "code": "chirp = sdk.create_chirp({\n 'title': 'The Godfather',\n 'classic': True,\n 'imdb': {\n 'id': 'tt0068646',\n 'rating': 9.2,\n },\n })\nprint chirp.identifier\n# we'll take 'ilovechirp' as an example", "language": "python" } ] } [/block] Playing the Chirp through the speakers is as simple as [block:code] { "codes": [ { "code": "chirp.chirp()", "language": "python" } ] } [/block] Or if you prefer to save the Chirp sound as a .wav file [block:code] { "codes": [ { "code": "chirp.save_wav('/tmp/my_new_chirp.wav')", "language": "python" } ] } [/block] Without a path, `Chirp.save_wav()` will create a file named `[identifier].wav` in the current directory, in that case `ilovechirp.wav`. ## Get a Chirp Now that our new chirp has been created, we can get the data associated with it at a later time. [block:code] { "codes": [ { "code": "another_chirp = sdk.get_chirp('ilovechirp')\nprint another_chirp.data['title']\n# The Godfather", "language": "python" } ] } [/block] And as this is also a `Chirp` object, you still have the the possibility to play the identifier on the speakers or download an audio file using the same methods as before. [block:api-header] { "type": "basic", "title": "3. Offline mode" } [/block] Offline mode is not yet fully supported for the Python SDK, meaning you'll need a host connected to the Internet in order to use Chirp functionalities. However if you don't need to store objects online and just want to play sound or generate a large amount of .wav files we provide a way to do so without querying our API. ## Play an Offline Chirp Instead of a dictionary, you can pass a string to the `Chirp.create_chirp()` method. That string needs to be a valid identifier. The created `Chirp` object will have the same methods as an Online Chirp. [block:code] { "codes": [ { "code": "chirp = sdk.create_chirp('hitchhiker')\nchirp.chirp()", "language": "python" } ] } [/block] * This is especially useful if you want to use the Python SDK alongside an Offline iOS or Android application such as [Gem Swap](doc:ios-offline-walkthrough) ## Save a .wav file If you need to generate a large amount of .wav files for your application we recommend you use the built in engine instead of having to rely on an open network connection. [block:code] { "codes": [ { "code": "sdk.save_wav(chirp, offline=True)", "language": "python" } ] } [/block] This will create a new file named `hitchhiker.wav`. [block:api-header] { "type": "basic", "title": "4. Protocols" } [/block] The Python SDK comes with our two default protocols. The Standard audible one with its 10 characters long identifier from the 32 characters alphabet and the Ultrasonic inaudible one with 8 hexadecimal characters. You can easily switch between protocols by calling the `sdk.set_protocol()` method. [block:code] { "codes": [ { "code": "sdk.set_protocol() # defaults to 'standard'\nprint sdk.create_chirp().identifier # 'ilovechirp'\n\nsdk.set_protocol('ultrasonic')\nprint sdk.create_chirp().identifier # 'df101010'", "language": "python" } ] } [/block] When using the Ultrasonic protocol, you might want to play the identifier on repeat. This is because ultrasounds are more sensitive to movement, direction and environment than audible sounds and thus, playing the identifier in streaming mode will ensure a higher reception ratio. [block:code] { "codes": [ { "code": "sdk.set_protocol('ultrasonic')\nchirp = sdk.create_chirp()\nsdk.streaming_interval = 500\nsdk.start_streaming(chirp)", "language": "python" } ] } [/block] This will play the same chirp every 0.5 seconds in a separate thread. You can close the thread and stop the loop with a call to `sdk.stop_streaming()`. If you don't explicitly set an streaming interval, it will default to 1 second.