Bigbookshelf (BBS)

An Audiobookshelf client for Smart TVs — LG webOS and Samsung Tizen.

Built on top of the Audiobookshelf Android app codebase, adapted for the TV experience with remote control navigation and a 10-foot UI. Originally developed for LG webOS; Tizen support added later.

Features

• Connect to any self-hosted Audiobookshelf server
• Browse audiobook and podcast libraries
• Full audio playback with progress tracking
• Remote control navigation (D-pad, media keys, color keys)
• Bookshelf grid with keyboard navigation
• Server connection management
• Sleep timer and playback speed controls
• Bookmarks and chapter navigation
• Download management
• Multi-language support (30+ languages)

Requirements

• LG Smart TV running webOS 3.0 or later, or Samsung Smart TV running Tizen 4.0 or later
• An Audiobookshelf server (self-hosted or remote)

Installation

Via IPK (Developer Mode)

1. Enable Developer Mode on your LG TV:

   • Open the Developer Mode app from the LG Content Store
   • Sign in with your LG account
   • Enable Developer Mode and note the TV's IP address

2. Install the IPK:

   # Install the webOS CLI tools
   npm install -g @webos-tools/cli
   
   # Set up your TV as a device
   ares-setup-device -a tv -a <TV_IP_ADDRESS>
   
   # Install the IPK
   ares-install -d tv bigbookshelf-webos.ipk
   
   # Launch the app
   ares-launch -d tv com.bigbookshelf.tv

Via SSH (rooted TV)

If your TV is rooted and reachable over SSH, you can pull the latest build straight from GitHub Releases onto the TV — no local build or scp required. The releases/latest/download/... URLs always resolve to the newest release.

LG webOS:

# SSH into the TV
ssh root@<TV_IP_ADDRESS>

# Download to the large user partition (the root fs is a tiny read-only
# overlay — opkg fails there with "Only have 0K bytes available").
curl -L -o /media/internal/bigbookshelf-webos.ipk \
  https://github.com/KTheMan/audiobookshelf-webos/releases/latest/download/bigbookshelf-webos.ipk

# Install via the webOS install service (routes into /media/developer; survives
# reboots). Use -i to watch status through to "installed".
luna-send -i 'luna://com.webos.appInstallService/dev/install' \
  '{"id":"com.bigbookshelf.tv","ipkUrl":"/media/internal/bigbookshelf-webos.ipk","subscribe":true}'

# Launch
luna-send -n 1 'luna://com.webos.service.applicationManager/launch' \
  '{"id":"com.bigbookshelf.tv"}'

opkg install also works on some firmwares, but only if the root partition has space — the install service above is the reliable route.

To upgrade later, re-run the curl + install steps; remove the old copy first with luna-send -n 1 'luna://com.webos.appInstallService/remove' '{"id":"com.bigbookshelf.tv"}' if an install refuses to overwrite.

Samsung Tizen:

# Download the latest WGT onto the TV (or your dev machine, for sdb install)
curl -L -o /tmp/bigbookshelf-tizen.wgt \
  https://github.com/KTheMan/audiobookshelf-webos/releases/latest/download/bigbookshelf-tizen.wgt

# Install with the Tizen Studio CLI from a connected dev machine
sdb connect <TV_IP_ADDRESS>
tizen install -n /tmp/bigbookshelf-tizen.wgt -t <device-id>

One-liner (download + install on a webOS TV in a single SSH command):

ssh root@<TV_IP_ADDRESS> 'curl -L -o /media/internal/bbs.ipk https://github.com/KTheMan/audiobookshelf-webos/releases/latest/download/bigbookshelf-webos.ipk && luna-send -n 5 "luna://com.webos.appInstallService/dev/install" "{\"id\":\"com.bigbookshelf.tv\",\"ipkUrl\":\"/media/internal/bbs.ipk\",\"subscribe\":true}"'

Via USB

1. Download bigbookshelf-webos.ipk (LG) or bigbookshelf-tizen.wgt (Samsung) from the latest release
2. Copy the package to a USB drive
3. On your TV, open the Developer Mode (LG) or Device Manager (Samsung) app
4. Select Install from USB and choose the package file

Development

Prerequisites

• Node.js 18+
• Docker (for builds) or the webOS TV SDK

Local Development

# Install dependencies
npm install

# Start the dev server (serves the dist/ folder)
npm run dev

Building

Using Docker (recommended):

docker build --network=host -t audiobookshelf-webos-builder .

Using the webOS TV SDK:

npm run build

Both methods produce:

• dist/ — Static web files ready for deployment
• bigbookshelf-webos.ipk — Installable package for webOS TVs

Project Structure

audiobookshelf-webos/
├── assets/                  # Static assets (CSS, fonts, images)
├── components/
│   ├── webos/              # TV-specific components
│   │   ├── AudioPlayerTV.vue
│   │   └── BookshelfGrid.vue
│   └── ...                 # Shared components from Android app
├── layouts/
│   └── default.vue         # TV-optimized layout
├── pages/                  # Route pages
├── plugins/
│   └── webos/              # webOS native plugins
│       ├── AbsAudioPlayer.js
│       ├── AbsDatabase.js
│       ├── AbsDownloader.js
│       ├── AbsFileSystem.js
│       ├── AbsLogger.js
│       ├── TVRemoteHandler.js
│       ├── capacitor-stubs/ # Capacitor API stubs for web
│       ├── index.js
│       └── polyfills.js    # ES5 polyfills for webOS 3.0
├── static/                 # Static files served as-is
├── store/                  # Vuex store modules
├── strings/                # i18n translation files
├── appinfo.json            # webOS app manifest
├── nuxt.config.js          # Nuxt configuration
├── tailwind.config.js      # Tailwind CSS configuration
└── Dockerfile              # Docker build environment

WebOS Plugins

The app uses custom webOS plugins that replace Capacitor native APIs:

Plugin	Purpose
AbsAudioPlayer	Audio playback via HTML5 Audio
AbsDatabase	Local storage for server configs and device data
AbsDownloader	Download management (stub — not supported on TV)
AbsFileSystem	File system access (stub — not supported on TV)
AbsLogger	Logging to localStorage
TVRemoteHandler	Remote control key handling and spatial navigation
polyfills.js	ES5 polyfills for webOS 3.0 compatibility

Building for Older webOS Versions

The app targets webOS 3.0+ via:

• Browserslist: Samsung >= 3, Chrome >= 38, Safari >= 6
• Babel transpilation: ES6+ → ES5 (arrow functions, async/await, template literals, etc.)
• Runtime polyfills: Map, URL, Promise, Array.from, crypto.getRandomValues, btoa

CI/CD

GitHub Actions automatically builds the IPK on push to main and creates releases on tag push.

# Tag a release
git tag -a v0.14.0 -m "Release v0.14.0"
git push --tags

The workflow will:

1. Build the Nuxt static site
2. Package as IPK
3. Create a GitHub Release with the IPK attached

Troubleshooting

App won't install:

• Ensure Developer Mode is enabled on your TV
• Check that your computer and TV are on the same network
• Verify the TV's IP address hasn't changed

App launches but shows a blank screen:

• Check your Audiobookshelf server is accessible from the TV
• Verify the server URL in the connection settings
• Check the TV's internet connection

Remote control not responding:

• The app uses D-pad navigation — try arrow keys
• Press Back to return to previous screens
• Media keys (play/pause/stop) are supported during playback

Contributing

Contributions are welcome! Please follow the existing code style and test on a real TV or the webOS Simulator when possible.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test on the webOS Simulator or a real TV
5. Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 — the same license as the Audiobookshelf Android app.

Credits

• Audiobookshelf by advplyr
• Audiobookshelf Android app — the foundation for this project
• Nuxt.js — the web framework
• Tailwind CSS — the CSS framework

Disclaimer

This is an unofficial client for Audiobookshelf. It is not affiliated with or endorsed by the Audiobookshelf project.