The Manual 説明書

curl -fsSL https://raw.githubusercontent.com/Shio-T0/Tubcal/main/install.sh | bash

Open a terminal, paste this command and press Enter. On many desktops CtrlAltT opens a terminal; if not, look for Terminal in your app menu. The installer works on Ubuntu, Fedora, Debian, Linux Mint, Arch, openSUSE and most other distributions.

What the installer does

1. Checks your system and shows a plan of what it will install. Nothing changes until you agree to it.
2. Asks which rooms you want, and a few options (both are in the tables below). A room you leave out isn't downloaded. Press Enter to accept the suggested choices.
3. Asks for your password if it needs to install packages from your distribution; the plan names them. Everything else, including Tubcal's own copies of the tools it uses, goes into your home folder and doesn't replace anything you already have.
4. Starts Tubcal once to check that it works, and only then reports that it's done.

It usually takes a few minutes, most of it downloading.

The rooms

Tubcal is made of nine rooms in three channels, and every room is optional. Tubcal shows only the rooms you install, so leaving some out also makes it smaller. If you leave out all of a channel's rooms, that channel isn't shown.

Options

To add a room later, type tubcal add and its name, for example tubcal add anime. tubcal remove takes one out again; what you saved, followed and watched there is kept, and comes back if you add the room again. To change the options, run the install command again: your earlier choices are already selected, and your data isn't touched.

On your phone

Tubcal also comes as an Android app, laid out for a phone, and it runs entirely on the phone. If your phone is plugged in while you install, the installer offers to put the app on it. You can also do it any time with tubcal phone, which installs the newest version, or updates the one already on the phone with the rooms it has.

The phone needs USB debugging turned on. Open Settings → About phone and tap Build number seven times, then turn on USB debugging in Settings → System → Developer options. When you plug the phone in, it asks whether to allow USB debugging from this computer: tap Allow. If your computer doesn't have adb (Android's debugging tool), Tubcal offers to install it.

The app keeps its own subscriptions and sign-ins, separate from the ones on your computer.

Before it installs the app, tubcal phone asks which rooms the phone should have, the same way the installer does on your computer. A new phone starts with the rooms your computer has. The phone app has every room except the Composing Room and By topic. Only the rooms you pick are installed on the phone: each room comes as a separate part of the app, downloaded straight from GitHub to the phone, and nothing is kept on your computer. To change the rooms later, plug the phone in and type tubcal phone add or tubcal phone remove and the room's name, for example tubcal phone add anime. Removing a room takes it off the phone. What you saved, followed and watched there stays on the phone and comes back if you add the room again. tubcal phone rooms lists what the phone has.

Opening Tubcal

Open Tubcal from your app menu, or type tubcal in a terminal. It opens in your web browser at 127.0.0.1:5000, an address that only works on the computer Tubcal is installed on. Then go on to First steps.

1. The home screen shows what to watch next: the video or episode you stopped halfway through, new uploads, who's live and what airs soon. Turn one of its three knobs, or press 1, 2 or 3, to go into the Social, Coding or Video channel. With 3D objects switched on, the home screen is a box instead: drag it sideways or press ← → to turn it, and each channel's side lists its rooms with links straight to the places inside them.
2. Add YouTube channels. In the Screening Room, press Add a channel and type the channel's handle (like @name) or paste its link. If you connect your YouTube account instead, all your subscriptions come in at once.
3. Add subreddits in Settings → Subscriptions, with Add a subscription. They appear in the Dispatch and in the daily paper.
4. For anime, connect a free AniList account. The Anime doesn't work without one.
5. If you use GitHub, follow some projects in the GitHub room with Follow a repo or person. Linking your account is optional; see Accounts.
6. Pick a skin with the skin button in any channel's bar, and switch off the rooms you won't use in Settings → Rooms.

The Edition makes a new paper every morning from what you follow. To get the first one straight away, press Recompose in Settings → The Edition.

Removing it completely

If you installed with the curl command, tubcal uninstall --purge also deletes the app and all its data. This can't be undone, so back up anything you want to keep first.

Every channel's bar also has a search button, Saved, Settings, the skin button and the three channel buttons. The Video panel folds into a narrow strip of icons if you want more room. On a phone-sized screen, the bars and panels move to the top of the page.

Getting from one to another

• On the home screen, turn a knob or press 1, 2 or 3. With 3D objects on, this works the same from the TV. From a channel's side, another number turns the box to that channel's side first; press the number again to go in, or 0 to turn back to the TV.
• From anywhere, press Space, then g, then s for Social, c for Coding or v for Video. a goes straight to the Anime and h to the home screen.
• Press / or CtrlK to search. From there you can jump to any room, search YouTube, Reddit and Hacker News together, or find something you saved.

The rooms

These are the rooms Tubcal starts with, if you install all of them. Switch any of them on or off in Settings → Rooms, and the rest of that channel is renumbered. The Anime can't be switched off there; leave it out when you install, or remove it with tubcal remove anime.

Look for the bookmark button. It's on videos, playlists and YouTube channels, Reddit posts and subreddits, Hacker News stories, anime shows, characters, voice actors and studios, forum threads, GitHub projects and releases, the Workbench's talks, podcasts and posts, and moments in the Archive. In the code editor, Spaceb saves the file you have open. To save any other page, open the Saved panel and press Save page.

The Saved panel

Press Saved in any channel's bar, or Space then s. A panel opens at the side of the screen, over the page you're on. In it you can save the current page, search what you've kept, open something, tick it as done, or remove it. If you remove something by mistake, press Undo in the message that appears.

The Saved page

The panel leads to the full Saved page, which has more room:

• a list down the left sorts what you've saved by channel, then by kind (videos, stories, shows and so on), with a count for each;
• To do and Done split what you've dealt with from what's still waiting;
• you can add a note to anything, and the search looks through your notes as well as titles;
• each kind has a layout of its own, or you can switch to a plain list, and sort newest first, oldest first or A to Z;
• Select lets you mark many things done, or remove them, in one go.

Each channel's guide on the home screen also says how much you've saved there, and links to it.

• Layout. The video plays large over a dark background. Below it are the title, the channel with a Subscribe button, Save, and a button that copies a link to the current second.
• Progress bar. It's divided into the video's chapters (hover to see their names), and a line above it rises where people replay most.
• Beside the video. The description, chapters and comments. Timestamps in the description jump to that moment, and links to other videos open in the player. With The Archive you also get a transcript and a summary.
• Corner player. Press Esc and the video shrinks to a corner and keeps playing while you browse. Videos you add to Up next play one after another.

Subtitles

Tubcal draws subtitles itself, so you can choose their font, size, colour, outline, background and position. The options are in Settings → Subtitles and in the player's subtitle menu, and they apply to every video and episode. You can set a preferred language there too.

Sound and speed

In Settings → Playback you can choose whether only the video in front plays sound or every open video does, and set the speed videos start at.

Anime episodes

Episodes have their own player, coloured to match the show. It adds:

• a Sub / Dub switch, remembered for each show;
• Skip opening and Next episode buttons (to skip openings automatically, turn that on in Settings → Anime);
• an eight-second countdown to the next episode when one ends;
• AniList updates: once you've watched most of an episode, it's marked as watched on your list.

Try the player demo on the tour.

Watching episodes

Episodes stream from public anime sites, the same ones the ani-cli tool uses. If one site fails, Tubcal tries another. These sites change often, which can break playback for a day or two; Tubcal checks for fixes each time it starts.

The Reckoner

The Reckoner adds up how long some episodes will take to watch. Point at any show and press C to add its next unwatched episode (aired ones only), and press again to add the one after. It shows the total time and when you'd finish if you started now. It sits in the page margin. See it on the tour.

The curtain call

When you finish the last episode of a season, Tubcal opens a screen for wrapping it up. You can score the season on your AniList scale, post in the last episode's discussion thread, write a review, and add the sequel to your list. If there's no sequel, it shows 終 ("the end"). It only opens for seasons that have finished airing, and waits until you close the player. You can also open it yourself with the Curtain call button on a show's page.

Opening themes

A show's page can play its opening song when you open it. Turn this on or off, and set how long and how loud, in Settings → Anime. The song button under the poster plays it whenever you like.

• The Archive transcribes the videos you watch. You can then search what was said, read a short summary of a video, or ask a question and get an answer that links to the moments it came from.
• The Edition can group posts about the same story even when they link to different pages, and write a short article for each top story, citing the posts it was written from. Without the AI it lists the headlines.
• By topic (in the Social channel, with 3D objects on) takes the 100 hottest stories on Hacker News and has the model sort them into five topics it picks itself. Stories that fit none of them are left out. A five-sided wooden column reads the headlines, then splits into five panels, one per topic, that you turn like the home screen's box. It sorts again when you open it and the last sort is over an hour old, or when you press Sort again. If you left it out when installing, add it with tubcal add topics.

Setting it up

1. If you want the Archive and didn't install it, add it with tubcal add archive. The Edition doesn't need it.
2. Install Ollama from ollama.com. It's a free app that runs AI models on your computer.
3. Download the two models Tubcal uses. In a terminal:
   two downloads, a few GB in total

   ollama pull nomic-embed-text   # for search
   ollama pull qwen3.5:9b         # for writing and answers

4. Restart Tubcal with tubcal restart. Settings → The Archive and Settings → The Edition show whether they found the models. By topic uses the model chosen as the Edition's Writer, or the Archive's model if the Writer is left on Same as The Archive.

Using The Archive

At first The Archive only keeps the videos you choose: open a video and press Add to the Archive in the panel beside it. To keep everything you watch, set What gets archived to Everything in Settings → The Archive. You search and ask questions in The Archive room, in the Video channel. Searching for a word works without the AI; questions and summaries need it.

Getting it

It's the installer's Terminal interface option. If you didn't pick it, run the install command again and switch it on; your other choices stay as they were. To play anything it needs mpv: with Distro extras on, the installer installs it for you.

Opening it

If Tubcal isn't running yet, it starts it, and says so while it waits.

Moving around

j and k move down and up, gg and G go to the top and the bottom, Enter or l opens or plays, h goes back. Tab switches between a room's views, and H and L between the rooms of a channel. The browser's keys work here too: Space g and s, c or v for the channels, g and a letter for a room. Space f finds anything, Space s opens Saved, / searches the list in front of you, and ? lists every key. When you press Space and wait, a small box shows what can follow.

As in vim, : types a command and :q quits. q on its own only closes what's open. O opens whatever you're looking at in the browser instead.

To act on several things at once, press V in a list and move with j and k to mark more rows. Then s saves them, a adds them to the queue, y copies their links, and d or x does to each row what dd or x does to one. u undoes saving or removing them all at once, and Esc leaves without doing anything.

What's there

Every room has a terminal version. Some things are only in the browser, and O takes you to them: Settings, connecting accounts, the Anime's browsing, seasons and community pages, GitHub's code and changes, and exporting what you saved.

• The Workbench lists each language's podcasts, talks, change log, popular projects and manuals. ]l goes to the next language.
• The Archive searches what was said in your videos (:ar and some words) and answers questions (:ask and your question). Enter on a line plays the video from that moment.
• GitHub shows your notifications and the pull requests and issues waiting on you. Enter reads the conversation beside the list. x marks a notification read, and dd marks it done; u takes that back within five seconds. In a tall enough window, your contributions over the past months are shown under the list.
• The Composing Room lists the files open in the browser's code editor, and the files changed next to them. Enter opens one in your own editor, and you're back in Tubcal when you quit it.

Writing

A note on something you saved (i in Saved), a question for the Archive (i in the Archive) and a comment on GitHub (i on an issue or pull request) are written in your own editor: nvim, unless you choose another. What you're writing about is shown below a cut line, and nothing below that line is sent. If you quit without changing the file, nothing is sent at all. The draft is deleted afterwards, and nvim keeps no copy of it, no undo history and nothing in the clipboard.

The radio

A podcast episode from the Workbench, or one you saved, plays on the radio. It keeps playing while you go to other rooms, and it shows at the bottom of the screen. A video pauses it, and the radio pauses a video. Space r r pauses and plays, Space r l skips 30 seconds ahead, Space r h goes back 15, and Space r x switches it off. It remembers where you stopped in each episode.

The sleep timer

:sleep 30 stops everything in 30 minutes (:sleep 1h30 works too). The sound fades out over the last 12 seconds, and your volume is back to normal next time. :sleep end stops when the video, episode or podcast that's playing ends, and :sleep off cancels it.

Pictures and colours

Thumbnails and covers are drawn sharp in terminals that support pictures (the kitty graphics protocol, as in kitty and Ghostty, or sixel, as in foot), and as coloured blocks in other terminals. The colours are your terminal's own. If you change your terminal's theme, Tubcal picks it up when you come back to the window, and :theme reads the colours again.

Privacy

• It only talks to Tubcal on your computer. Pictures come through Tubcal, and so do videos: mpv plays them from your own computer. The one exception is the radio, which plays a podcast from the podcast's own site, as the browser does.
• A private session (tubcal tui --private, or Space P) records nothing: no history, no place to resume from, no episodes marked on AniList, and pictures aren't saved to disk. PRIV shows at the bottom while it's on.
• What the terminal remembers is the room you were in, which stories you've read and where you stopped in podcasts. :history clear forgets the stories and podcasts. Your watch history is the same as in the browser; you can clear it in Settings.

Its own settings

Almost everything is shared with the browser. The few things only the terminal uses go in ~/.config/tubcal/tui.toml, for example editor = "hx" for another editor, images = "off" for no pictures, or icons = "unicode" if your font has no Nerd Font icons. :checkhealth shows what works in your terminal.

You can change keys there too, written the way vim writes them. Under [keys], the line "<C-n>" = "down" makes CtrlN move down, and "K" = "" turns K off. A room's own keys go under its name, for example [keys.youtube]. :map lists every key with the name of its action. If something in the file can't work, Tubcal says what when it starts, and :messages keeps the list.

• Who can open it. Only the computer it's installed on. Other devices on your Wi-Fi can't.
• YouTube. Tubcal fetches YouTube without signing in and without cookies, so YouTube can't link your searches, feeds and viewing into a profile. The one exception: if you connect your YouTube account, Tubcal uses it to import your subscriptions.
• Which sites it connects to. The ones you use through it: YouTube, Reddit, Hacker News, AniList and GitHub, each only if you have that room. Also public YouTube mirrors for trending and as a search backup, the anime streaming sites while you watch an episode, AnimeThemes for opening songs, the Workbench's podcast and blog feeds, and update checks for its video tools.
• The AI. It runs on your computer, and your transcripts stay there.

Where your data is

Everything you follow, watch, save and connect, your saved things and their notes, and The Archive's transcripts, is kept in a folder called data:

Backing up

Stop Tubcal (tubcal stop), copy the whole data folder somewhere safe, then start it again. To restore it, or to move to a new computer, install Tubcal, stop it, and put your copy of the folder back in the same place.

Clearing your history

Settings → Watch history shows how many videos Tubcal remembers and can clear them. The history is only used for suggestions and for resuming videos, and it stays on your computer.

Tubcal is free software under the GNU General Public License, version 3 or (at your option) any later version. You can use it, share it and change it, and if you share a changed version, you must share its source code too. It comes with no warranty. See the licence.

Anime playback builds on other free projects (ani-cli, anipy-api and weeb-cli), credited in THIRD_PARTY_NOTICES.md. Settings → About lists the licence and every library Tubcal uses.