141 lines
5.3 KiB
Markdown
141 lines
5.3 KiB
Markdown
# mangabaka-seeder
|
|
|
|
`mbseed` is a command-line tool for seeding edits to the
|
|
[MangaBaka](https://mangabaka.org) manga/comics database, in the spirit of
|
|
[yambs](https://codeberg.org/derat/yambs) for MusicBrainz.
|
|
|
|
Today it does one thing well: **given a Webtoons series URL, it finds every
|
|
cover that series has used, current and historical, and requests them added to
|
|
the matching MangaBaka series**. The current poster becomes the main (default)
|
|
cover for the edition's language.
|
|
|
|
More sources (Tapas, Tappytoon, …) and more kinds of edits are planned; see
|
|
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for how they plug in.
|
|
|
|
## How it works
|
|
|
|
1. **Read the series.** It reads the Webtoons page: title, `title_no`, language,
|
|
and official or canvas.
|
|
2. **Find the MangaBaka series.** It searches MangaBaka by title and picks the
|
|
series whose Webtoons link has the same `title_no`.
|
|
3. **Collect covers.**
|
|
- **Current:** the portrait poster, the square thumbnail, and the banner and
|
|
hero art.
|
|
- **Historical:** the cover images in archived copies of the series page on
|
|
the [Wayback Machine](https://web.archive.org), up to one snapshot per
|
|
month.
|
|
4. **Check each image.**
|
|
- It downloads each image to get its size and hash.
|
|
- It classifies the image by shape: portrait → `volume`, square → `other`,
|
|
wide → `banner`.
|
|
- It drops duplicates and images MangaBaka already has.
|
|
5. **Build the submission.** The submission keeps all existing covers and adds
|
|
the new ones. The current poster is the default, or the square for canvas
|
|
series, which have no poster. Every new cover gets a note recording where
|
|
and when it was seen.
|
|
6. **Hand it to you.** It either submits through the MangaBaka API (with your
|
|
confirmation) or opens a local review page to help you enter it by hand.
|
|
|
|
Nothing reaches MangaBaka without your confirmation, and API submissions always
|
|
go to review (`save_mode: "review"`).
|
|
|
|
## Installation
|
|
|
|
Requires Node.js 22 or newer.
|
|
|
|
```sh
|
|
npm install
|
|
npm run build
|
|
npm link # puts `mbseed` on your PATH
|
|
```
|
|
|
|
## Usage
|
|
|
|
```
|
|
Usage: mbseed [options] <URL>
|
|
|
|
Options:
|
|
--action <print|serve|submit> What to do with the seed
|
|
(default: submit if MANGABAKA_TOKEN is set, else serve)
|
|
--series <id> MangaBaka series id (skips automatic matching)
|
|
--no-history Only use covers currently on the source page
|
|
--history-limit <n> Max archived snapshots to inspect (default 60)
|
|
--json With --action print: print the seed as JSON
|
|
--yes With --action submit: don't ask for confirmation
|
|
--addr <host:port> With --action serve: listen address (default localhost:8999)
|
|
--verbose Log every HTTP request
|
|
-h, --help Show help
|
|
```
|
|
|
|
Environment:
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `MANGABAKA_TOKEN` | Personal access token (`mb-…`). Enables `--action submit`. |
|
|
| `MANGABAKA_API` | API base URL (default `https://api.mangabaka.org`). |
|
|
|
|
### Without API access (most users)
|
|
|
|
MangaBaka's submissions API is only open to contributors, or to users with at
|
|
least 25 approved submissions. Without a token, `mbseed` starts a local review
|
|
page:
|
|
|
|
```sh
|
|
mbseed https://www.webtoons.com/en/fantasy/tower-of-god/list?title_no=95
|
|
# → Review page at http://localhost:8999
|
|
```
|
|
|
|
The page shows each new cover with its thumbnail, size, suggested type,
|
|
language and note. Tick the ones you want, copy their URLs, and use the link to
|
|
open MangaBaka's cover form for the series. The form can't be pre-filled
|
|
automatically.
|
|
|
|
### With API access
|
|
|
|
```sh
|
|
export MANGABAKA_TOKEN=mb-...
|
|
mbseed https://www.webtoons.com/en/fantasy/tower-of-god/list?title_no=95
|
|
```
|
|
|
|
`mbseed` fetches the current cover set, shows MangaBaka's preview diff, asks
|
|
for confirmation and submits the request for review. If the API refuses access
|
|
(403), it falls back to the review page.
|
|
|
|
### Just looking
|
|
|
|
```sh
|
|
mbseed --action print https://www.webtoons.com/en/fantasy/tower-of-god/list?title_no=95
|
|
mbseed --action print --json <URL> > seed.json
|
|
```
|
|
|
|
## Supported sources
|
|
|
|
| Source | URLs | Current covers | Historical covers |
|
|
|---|---|---|---|
|
|
| WEBTOON (official & canvas) | `https://www.webtoons.com/<lang>/…/list?title_no=N`, `m.webtoons.com` | poster, square, banner, foreground | Wayback Machine |
|
|
|
|
Each Webtoons language edition has its own `title_no`. Run `mbseed` once per
|
|
edition URL; the covers are tagged with that edition's language.
|
|
|
|
## Notes and limitations
|
|
|
|
- **Image hosting.** Covers are submitted as URLs on Webtoons' image server
|
|
(`swebtoon-phinf.pstatic.net`), at their original size. We haven't confirmed
|
|
that MangaBaka accepts this host.
|
|
- **Some covers may only exist in the archive.** If an old cover is no longer
|
|
on Webtoons' server, its archive.org copy is used instead.
|
|
- **Not everything is a cover.** Some historical images are promotional or
|
|
landing-page art. Review the list before submitting.
|
|
- **Requests are rate-limited** to stay polite to Webtoons, the Wayback Machine
|
|
and MangaBaka.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
npm test # vitest, fixture-based, no network
|
|
npm run typecheck
|
|
npm run dev -- --action print <URL> # run from source with tsx
|
|
```
|
|
|
|
To add a new source, see [docs/ARCHITECTURE.md § 4.1](docs/ARCHITECTURE.md#41-the-source-interface-extension-point).
|