Metadata-Version: 2.1
Name: etc-player
Version: 1.0.0
Summary: 
License: MIT
Author: Brian Kohan
Author-email: bckohan@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: django (>=4.2,<5.0)
Requires-Dist: django-enum (>=1.3.3,<2.0.0)
Requires-Dist: enum-properties (>=1.8.0,<2.0.0)
Requires-Dist: gunicorn (>=20.1.0,<21.0.0)
Requires-Dist: tzlocal (>=4.3,<5.0)
Description-Content-Type: text/markdown

# etc_design_player

Use a [Raspberry Pi](https://www.raspberrypi.com/) to play audio wave files on a 
configurable schedule or on demand via a web interface. This software was 
originally developed to time the audio playback of museum exhibit audio tracks
with the opening schedule of the museum.


## Installation

Install the Raspberry Pi operating system and connect it to your local network.
**Change the hostname of your Raspberry Pi to a memorable unique name** - this name
will be used access the scheduler later. The hostname can be changed by clicking
the raspberry in the upper left menu and selecting "Preferences" -> 
"Raspberry Pi Configuration" -> "System" -> "Hostname". While you have the 
preferences open, also enable ssh access by selecting the "Interfaces"
and toggling SSH on. Click save and reboot.

Most wifi networks will allow you to access your Raspberry Pi over the network
using the hostname you set. Only if your network does not will you have to use
its IP address instead. [There are numerous ways to do determine the IP](https://letmegooglethat.com/?q=How+do+I+determine+my+Raspberry+PI%27s+IP+address%3F) - 
but be aware that power outages and other circumstances can change the IP 
address of your Pi. For that reason it is advisable to give it a static IP 
address on your network - which you can do by configuring the wifi router or 
asking your local tech support for help.

 - To install from the Raspberry Pi Desktop:
    * Download the [latest package](https://github.com/bckohan/etc_design_player/raw/main/etc_player.zip).
    * Unzip the downloaded package.
    * Double click on the install.sh file and select "execute in terminal".
 - To install from your computer's terminal: (replace "hostname" and "pi" with 
   your Pi's hostname and account username respectively). 

    ```bash
      ssh pi@hostname
      wget --no-check-certificate --content-disposition https://github.com/bckohan/etc_design_player/raw/main/etc_player.zip
      unzip ./etc_player.zip
      cd ./etc_player
      ./install.sh
    ```

 - After a few minutes the install script will prompt you to enter a username
   and password. This will be the account you use to login to the web interface
   to configure the playback. Once the install script disappears the install
   is complete.
 - To configure your playback from a computer on the same wifi network you can
   access from: `http://hostname/admin` where hostname is the hostname you set
   earlier or if on your Raspberry Pi's desktop you may also use
   http://localhost/admin

## Usage

Most wifi networks will allow you to access the scheduler interface through
`http://hostname/admin` (where hostname is the hostname you set during install).
If this does not work you may need to use the IP  address instead. As mentioned
before there are numerous ways to determine the IP.

When accessing the admin the username/password will be the credentials you 
setup when you ran install.sh.

Upload a wave file by adding a wave. There is no progress indicator on the wave
file upload interface - so be patient and wait for the page to refresh before 
navigating after you hit save.

Scheduling is done per-day-of-the-week. Only one contiguous block of time per
day can be scheduled. To schedule a playback, create a playlist from one or
more wave files. The playlist will loop until the scheduled time ends, and the
currently playing wave file will be allowed to finish before the audio
terminates after the end time is reached.

The configured schedule will always be honored unless you add a Manual Override.
Manual Overrides can be scheduled for specific dates into the future and may
start or stop playlists. Volume control and play/stop functions can be accessed
from the main page: `http://hostname/`

**_NOTE:_**  On some hosts (OSX) you may need to use `hostname.local` instead of 
`hostname`.

## For Developers

This software uses the [Django](https://www.djangoproject.com/) webserver to 
provide the user interface.

The [Poetry](https://python-poetry.org/) build tool is used to manage 
dependencies and build the project:

You may also want to install [pyaudio](https://pypi.org/project/PyAudio/) for 
audio support on OSX.

`poetry install -E all`

Run the tests:
`poetry run ./etc_player/player.py test`

Run the development server:
   * `poetry run ./etc_player/player.py migrate`
   * `poetry run ./etc_player/player.py runserver`

The operational environment is configured using scripts located in 
etc_player/ops. ``install.sh`` can be referenced to see how they are installed 
onto the system. The architecture serves the Django web interface using 
gunicorn proxied through nginx. The audio player script is managed as a simple 
always-on systemd service which makes the audio playback robust to power 
interruptions and other system failures.

