Getting started and how the poller works

01What to install

The poller is plain Python and runs on macOS, Linux and Windows. Every command box in these guides has a tab for each system. Your computer is picked automatically, and you can change it once in the sidebar to switch every box at the same time.

You type commands into a terminal: the Terminal app on macOS, a terminal window on Linux, or PowerShell on Windows.

Install them all:

# Homebrew, the macOS package manager (skip if "brew --version" already works)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# The tools
brew install python@3.13 git gh node
brew install --cask visual-studio-code

# Ubuntu or Debian. On Fedora, use "sudo dnf install" with the same names.
sudo apt update
sudo apt install -y python3 python3-venv python3-pip git gh curl
sudo snap install code --classic                        # VS Code

# Node.js 22 (only for version 2 and the app)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# winget comes with Windows 10 and 11. Run these in PowerShell:
winget install -e --id Python.Python.3.13
winget install -e --id Git.Git
winget install -e --id GitHub.cli
winget install -e --id Microsoft.VisualStudioCode
winget install -e --id OpenJS.NodeJS.LTS               # only for version 2 and the app

# Close PowerShell and open it again so the new commands are found.

Playwright, the browser the poller uses to read seat maps, is installed inside the project in section 3. If gh is not found on an older Linux, follow GitHub's Linux instructions.

02Git and GitHub setup

The code lives in a private GitHub repository. In the commands below, replace YOUR-GITHUB-NAME with the account that owns it. These steps recreate the setup on any machine. If git is new to you, read GitHub's Hello World first (20 minutes).

1. Tell git who you are (once per machine):

   bashCopy

   git config --global user.name "Your Name"
   git config --global user.email "you@example.com"
   git config --global init.defaultBranch main

2. Log in to GitHub (the same on every system). The tool creates an SSH key for you, so you never type a password again:

   bashCopy

   gh auth login        # choose: GitHub.com, SSH, generate a new key, log in with browser
   gh auth status       # should say "Logged in to github.com"
   ssh -T git@github.com

3. Download (clone) the code and create the private settings file:

   macOSLinuxWindows

   Copy

   git clone git@github.com:YOUR-GITHUB-NAME/bms-poller.git
   cd bms-poller
   cp .env.example .env     # then fill in your values; .env is never uploaded

4. Make every change on its own branch, then open a pull request:

   bashCopy

   git checkout main && git pull
   git checkout -b fix/blank-links         # a new branch named after the change
   # edit files, run, test
   git add -A && git commit -m "Skip alert when scraper finds zero groups"
   git push -u origin fix/blank-links
   gh pr create --fill                     # opens a pull request; merge it on GitHub

5. Never upload secrets. The .gitignore file already keeps out .env, state.json, notified_pairs.json, bms_state.json, logs/, diag/ and dump_*.json. If a token ever ends up in a commit, treat it as stolen: log out of BookMyShow in that browser, log in again, and remove the commit from history with git filter-repo (GitHub's guide).

03Install and run the poller

The first run takes about ten minutes. The slow part is copying your BookMyShow login from Chrome, which this version still needs. The bug guide shows how to replace that with a one-time login.

1. Go to the project folder, create the virtual environment, turn it on, and install the packages:

   macOSLinuxWindows

   Copy

   cd ~/Desktop/"Book myshow room"/bms-poller      # or wherever you cloned it
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   playwright install chromium                      # only needed when V2_SCRAPER_ENABLED=1

   While the virtual environment is on, your prompt starts with (.venv). In a new terminal window, run the cd line and the activate line again before using the poller. From here on, python means the virtual environment's Python on every system.

2. Copy .env.example to .env and set the target: EVENT_CODE (the ET000… code in the movie's BookMyShow web address), DATE_CODE as year-month-day like 20261012, REGION_CODE (HYD) and REGION_SLUG (hyderabad).

3. Copy your login from Chrome. Open in.bookmyshow.com while logged in, press F12 (Windows, Linux) or Option-Command-I (macOS) to open DevTools, choose the Network tab, type api/ in the filter box, click any request, and copy these request headers into .env: x-access-token, x-lsid, x-member-id, x-bms-id, x-advertiser-id, plus your mobile number and email.

4. Optional, for alerts that name the exact seats: in the DevTools Console tab on a BookMyShow page run

   jsCopy

   JSON.stringify({cookies: document.cookie, ls: {...localStorage}, ss: {...sessionStorage}})

   Save the output as a file named test.txt in the folder that contains bms-poller (one level up), run python build_state.py to create bms_state.json, then set V2_SCRAPER_ENABLED=1 and GROUP_SIZE=2 (or 3, 4) in .env.

5. Set up the two alert channels: NTFY_TOPIC (install the ntfy app on your phone and subscribe to the same topic name) and a 16-character Gmail app password in SMTP_APP_PASSWORD.

6. Run it (the same on every system, with the virtual environment on):

   bashCopy

   python poller.py

   A healthy start prints monitoring only venues matching: [...] and loaded state: N prior sessions. Then every cycle prints something like showtimes: 12/270 sessions match filter (9 bookable), followed by either no changes this cycle or ALERTING on N changes, then sleeping 60s.

7. Stop with Ctrl-C (Control-C on macOS too). The poller remembers what it saw in state.json, so restarting does not send the same alerts again.

04Settings: the .env file

Everything the poller does is controlled by the .env file. It is read once at start, so after changing it, restart the poller.

The movie title in the alert text is typed into the code as "Spider-Man: Brand New Day". There is no MOVIE_NAME setting yet (bug 7).

05The big picture (architecture)

One Python program, five files of code, three memory files, and three outside services.

Dashed boxes are outside the program. Nothing here is a server: there is no database, no web page and no login screen, which is why the login headers must be pasted by hand.

06What happens every minute (flow)

In words: each cycle is one request for every show of the movie in the city. The poller only opens a seat map when a show's availability number went up or a bookable show appeared for the first time. With the V2 scraper on, a show whose free groups were all announced before is skipped.

The red parts are the two gaps covered in the bug guide: a seat read that finds zero groups still sends an alert (that is the blank-alert bug), and an error 400 is printed to the log but never reported to you.

07Alerts and the memory files

Every alert goes out on two channels at the same time from notifier.py. Three JSON files next to the code remember what has been seen, so a restart does not repeat alerts.

Channels. notify() runs send_ntfy and send_email in parallel. ntfy gets a message with the topic, title, text and priority 5 (urgent). Email goes through Gmail with the app password. If one channel fails, the other still goes out, and the failure is written to the log.

What an alert contains. Movie name (fixed in the code), theatre and its code, show time and show id, date, the change (for example "sold out → few seats"), the seat groups if the V2 scraper found any, and a direct link to the seat page: https://in.bookmyshow.com/movies/{region}/seat-layout/{event}/{venue}/{session}/{date}.

Availability numbers as the poller reads them: 0 sold out, 1 few seats, 2 filling fast, 3 available. The API also says whether the "Book" button works (cta.type is showTimeRedirect) or shows a sold-out message (toast). In the saved sample both agreed for all 270 shows.

Shows that disappear from one answer are removed from state.json right away. That keeps the file small, but it is also why "New show opened" alerts sometimes repeat (bug 4).

08Running in the background

Running python poller.py stops when you close the terminal. To keep it running, hand it to your system's background service manager. macOS uses launchd, Linux uses systemd, and Windows uses Task Scheduler. The original setup runs on a Mac with launchd and on an Oracle cloud server with systemd.

cp deploy/com.sriram.bms-poller.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.sriram.bms-poller.plist     # start now and at every login
launchctl list | grep bms                                              # shows process id and last exit code
launchctl unload ~/Library/LaunchAgents/com.sriram.bms-poller.plist   # stop
tail -f logs/poller.out.log                                            # watch the log live

sudo systemctl status bms-poller
sudo journalctl -u bms-poller -f        # live log
sudo systemctl stop bms-poller          # stop
nano ~/bms-poller/.env && sudo systemctl restart bms-poller

$dir = (Get-Location).Path
New-Item -ItemType Directory -Force "$dir\logs" | Out-Null
$action   = New-ScheduledTaskAction -Execute "cmd.exe" -WorkingDirectory $dir `
            -Argument "/c .venv\Scripts\python.exe poller.py >> logs\poller.out.log 2>&1"
$trigger  = New-ScheduledTaskTrigger -AtLogOn
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) `
            -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "BMS Poller" -Action $action -Trigger $trigger -Settings $settings
Start-ScheduledTask -TaskName "BMS Poller"

Get-ScheduledTask -TaskName "BMS Poller" | Get-ScheduledTaskInfo   # last run time and result
Stop-ScheduledTask  -TaskName "BMS Poller"                          # stop
Start-ScheduledTask -TaskName "BMS Poller"                          # start again, for example after editing .env
Unregister-ScheduledTask -TaskName "BMS Poller" -Confirm:$false     # remove the task completely
Get-Content logs\poller.out.log -Wait -Tail 50                      # watch the log live

09When something goes wrong

Start by reading the last 50 lines of the log file. Every problem below has its own tell-tale line.

tail -n 50 logs/poller.out.log

sudo journalctl -u bms-poller -n 50 --no-pager     # when it runs as a service
# When you run "python poller.py" by hand, the log is printed in that terminal.

Get-Content logs\poller.out.log -Tail 50

Two quick checks. The first proves the install is fine. The second replays the last recorded seat map and prints the seat groups the code sees.

.venv/bin/python -c "import bms, poller"
.venv/bin/python adjacency.py diag/canvas_draw_log.json

.venv/bin/python -c "import bms, poller"
.venv/bin/python adjacency.py diag/canvas_draw_log.json

.venv\Scripts\python -c "import bms, poller"
.venv\Scripts\python adjacency.py diag\canvas_draw_log.json