NIGHTSCRIBE

What is NightScribe?

Four missions, one loop:

1. Plan the night: the best targets visible from your observatory, under your real constraints, ranked and explained.

2. Understand every object: orbital and physical parameters translated into accurate, engaging explanations, in Spanish and English.

3. Capture and reduce: it drives your mount and camera through CCDciel or NINA/PINS, and it calibrates, stacks and measures your own frames: photometry (variables, exoplanets, supernovae) and MPC-ready astrometry of minor bodies, without leaving the window.

4. Tell it: a bilingual (ES/EN) draft and the night's charts, written with the real data of your session.

Every chosen target becomes a project: a persistent entity with its own folder that walks you through Card → Capture → Analysis → Publishing without asking again what it already knows (coordinates, window, magnitude, exposure plan). Weeks later the project is still there: follow-up visits, the light curve, the final outcome.

What you can follow

Eight kinds of targets share the same list every night, with the Sun and the sky as context. Each one has its own chapter in the user guide: what it is, why it matters tonight and how it is measured.

The app

Six screens of the running program, with real observations: the object card, the track & stack, the photometry, a transit reduced by EXOTIC, a light curve and a measurement. Click any of them to see it larger.

What you need

No account, no registration, no telemetry: NightScribe runs on your computer and talks only to the public data services listed below.

Your first five minutes

1. Install. No Python needed: every file lives on the Releases page. Pick your system: - Windows: run the NightScribeSetup-*.exe installer (per-user, no admin rights). It is not code signed, so Windows has two ways to stop it: SmartScreen warns and lets you through with More info → Run anyway, while Smart App Control (Windows 11, on by default on new installations) blocks it with no way through at all. Prefer not to install anything? Unzip the portable NightScribe-*-windows-x64.zip and run nightscribe.exe gui (the same two gates apply to it). What to do about Smart App Control is in the guide. - Linux: install the .deb (Debian, Ubuntu, Mint) with sudo apt install ./nightscribe_*_amd64.deb, or the .rpm (Fedora, openSUSE) with sudo dnf install ./nightscribe-*.x86_64.rpm, then run nightscribe gui.

   The full per-system steps are in INSTALL.md. Running from a source checkout is the last option there, for contributors.

1. The wizard asks for one thing: your observatory. Type your MPC code and your coordinates are filled in from the MPC list; or enter name, latitude, longitude and altitude by hand.

2. The Tonight view (from + NEW PROJECT in the header) computes your night on its own: it downloads the target lists, filters them by your site and gear, and ranks everything.

3. Click any target and you get its full explained card. Like what you see? One button: Create project.

4. When you have a minute, open Tools → Settings…: horizon file, limiting magnitude, camera plate scale, session defaults. Everything has a sensible default; nothing else is mandatory.

From source (contributors)

NightScribe also runs from a checkout; the full, per-system walkthrough is in INSTALL.md. The short version:

python3 -m venv --system-site-packages .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m nightscribe gui

Video tutorials

The tutorial playlist on YouTube collects the walkthroughs of the project. The narration is in Spanish and the interface in English; the user guide is the written reference.

A whole night (and the weeks after)

The guide walks a real night from the first click to the report. The short version:

1. Late afternoon. One click on + NEW PROJECT computes the night: the best target first, a chip saying how lit the Moon is and another announcing a shadow transit on Jupiter, and a one-line reason for the top row.

2. You click it. The card says what the object is, how fast it moves and, because it knows your camera, your longest trail-free exposure. You press Create project.

3. Plan and capture. Size the session; the app confirms it fits inside the safe window. Export the ephemeris and the sequence, or, with CCDciel or NINA/PINS connected, send the plan and start the run without leaving the app.

4. Analysis. Back home you open the visit in the editor: it solves the reference frame, registers the sequence and stacks it following the object, measures every observation and checks the result against the other stations. The MPC report comes out ready to send.

5. The weeks after. The journal remembers that night by itself, the light curve grows, the dashboard nudges you when a revisit is due and the bilingual draft is already written with the real session data.

Where the data comes from

Tonight's list and the object cards are fed by public services, each with its own refresh: NEOfixer, the MPC (PCCP, observatory codes, published observations), COBS, Rochester Astronomy, ExoClock, ESA NEOCC, the HADS catalogue, AAVSO (VSX, forum, campaigns and photometry), ALeRCE/ZTF, JPL (SBDB, Horizons, CAD), SIMBAD, TNS, the NASA Exoplanet Archive, VizieR, NOAA SWPC, SILSO, NASA SDO and the DESI Legacy Survey.

All network access goes through an SQLite cache with per-source TTLs: repeat queries are instant and free for the service, and a source that is down never breaks the rest of the app. Sun, Moon and planet positions, the sky calendar and the whole reduction (registration, stack, measurement, periods) are computed locally, with no service involved. The full table, with what each source gives you and whether it needs a key, is in docs/DATA_SOURCES.md.

Optional integrations

Everything below is optional; each missing piece degrades gracefully and tells you so. Configure them in Tools → Settings → Integrations.

Your data stays with you

Everything NightScribe knows lives in a local SQLite database in your user's data directory: the HTTP cache, your projects, sessions, photometry, campaigns and settings. Each project gets its own container folder (plans, sequences, reports, charts, posts) under a root you choose and can change later. No accounts, no cloud, no telemetry. Uninstall and delete the folder: nothing remains anywhere else.

Quickstart and CLI

Install first (see Your first five minutes). Then everything the GUI does for planning and publishing has a command-line counterpart:

nightscribe gui        # desktop app
nightscribe tonight    # best targets tonight (CLI)

tonight, explore, post, solar, blink, sequence, history, project and inject are the rest (--help on each for the details), and chapter 09. The command line has the whole list. The reduction (calibration, track & stack, astrometry, photometry, periods) lives in the GUI.

See INSTALL.md for the full per-OS instructions (the standalone installer and the Linux packages first), and CONTRIBUTING.md to hack on it.

Documentation

The user guide (español) walks the whole cycle, from the first run to the MPC report, in short chapters with the "why" of each option. It is published as a website: <https://irydeo.github.io/nightscribe/> (Help → User guide (web)).

Design, architecture, data sources, scoring, workflows and every design decision live in docs/, in Spanish and English.

Something missing, wrong or unclear? Open an issue.

Licence

NightScribe is free software, published under the GPL v3: you can use it, study it, change it and share it, and whatever you pass on stays free for the next person. There is no paid edition and no locked feature.

User guide

The guide, chapter by chapter

Advanced guide: For when you want the why: the physics, the formats, the algorithms and the decisions behind them, written down.