starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[PR #4868] [Enhancement] "Clips" feature for settings bookmarks and adding notes - SERVER-SIDE #4360

New Issue
Open
opened 2026-04-25 00:19:25 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:19:25 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/4868
Author: @fonix232
Created: 11/27/2025
Status: 🔄 Open

Base: master ← Head: feat/clips_serverside

📝 Commits (2)

  • 657cb07 feat: Add AudioClip data model
  • cdb0bbb feat: Add AudioClip to database proper

📊 Changes

8 files changed (+2202 additions, -0 deletions)

View changed files

📝 server/Database.js (+6 -0)
📝 server/controllers/MeController.js (+166 -0)
➕ server/migrations/v2.31.0-audio-clips.js (+171 -0)
➕ server/models/AudioClip.js (+329 -0)
📝 server/routers/ApiRouter.js (+5 -0)
➕ test/server/controllers/MeController.clips.test.js (+806 -0)
➕ test/server/migrations/v2.31.0-audio-clips.test.js (+284 -0)
➕ test/server/models/AudioClip.test.js (+435 -0)

📄 Description

Brief summary

First half of the implementation of the "Clips" feature, an upgrade over Bookmarks - the ability to select a range of an audiobook, instead of just a singular timestamp.

Which issue is fixed?

#3088

In-depth Description

This PR:

  • Adds the new AudioClip data class
    • Every item is bound to a user and libraryItem (and optionally episode)
    • Every item must have a startTime (>0) and endTime (>startTime)
    • Currently, there's no validation for endTime being beyond libraryItem.duration (potential improvement for the future?)
    • Every item must have a title (same as AudioBookmarkObject's title property
    • Every item can have an optional notes field for lengthier information (such as, transcription, if/when it gets implemented)
    • Every item has a createdAt and updatedAt field, managed by the DBO itself
  • Added AudioClip to the sequelize Database handler
  • Added relevant CRUD functionality to MeController
  • Added routing to provide API via ApiRouter
  • Added database migration
    • Also covers importing existing bookmarks as Clips, with a default 10 second range defined from bookmark timestamp. Users then can freely edit the clips to cover the full range they want it to. (Potentially a callout on the UI would be beneficial to redirect the users and let them update all newly created Clips?)

Future features/TODOs:

  • Implement ffmpeg call to extract audio into a specified folder
    • This can be either on-the-fly (whenever the user requests the download)
    • Or it can be on every update (whenever an AudioClip is saved/updated, the audio gets extracted). I prefer this solution as it means downloads are instantaneous
  • Add transcription to the AudioClip
    • And with the transcription, one can dig into a linked EPUB/eBook file and create a Kindle style highlight metadata file (or, any other format, I'm open to suggestions)
  • Add AI based cleanup. Selecting the exact precise range is often hard/impossible, but there are AI models out there that can analyse an audio file, and remove other voices from the beginning/end without clipping issues

How have you tested this?

My follow-up PR will implement the frontend changes (clips modal interface, although I am reworking the idea at the moment). The barebones UI test environment that I've created so far verified:

  • Standard CRUD operations work
  • API returns appropriate error messages when a bad request is sent
  • Logs show appropriate debug/warning/error logs

Beyond this, I've also written test coverage for all new functionality wherever possible - which make up roughly 3/4 of this PR

Screenshots

Very barebones initial attempt at UI, more functional than good UX:

image

UI is not part of this PR!

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/advplyr/audiobookshelf/pull/4868 **Author:** [@fonix232](https://github.com/fonix232) **Created:** 11/27/2025 **Status:** 🔄 Open **Base:** `master` ← **Head:** `feat/clips_serverside` --- ### 📝 Commits (2) - [`657cb07`](https://github.com/advplyr/audiobookshelf/commit/657cb075ee2d7ede686b7b9ec799786021ae6ab8) feat: Add AudioClip data model - [`cdb0bbb`](https://github.com/advplyr/audiobookshelf/commit/cdb0bbb4d2feeae6a7cea8943c04a3909523b219) feat: Add AudioClip to database proper ### 📊 Changes **8 files changed** (+2202 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `server/Database.js` (+6 -0) 📝 `server/controllers/MeController.js` (+166 -0) ➕ `server/migrations/v2.31.0-audio-clips.js` (+171 -0) ➕ `server/models/AudioClip.js` (+329 -0) 📝 `server/routers/ApiRouter.js` (+5 -0) ➕ `test/server/controllers/MeController.clips.test.js` (+806 -0) ➕ `test/server/migrations/v2.31.0-audio-clips.test.js` (+284 -0) ➕ `test/server/models/AudioClip.test.js` (+435 -0) </details> ### 📄 Description ## Brief summary First half of the implementation of the "Clips" feature, an upgrade over Bookmarks - the ability to select a range of an audiobook, instead of just a singular timestamp. ## Which issue is fixed? #3088 ## In-depth Description This PR: - Adds the new `AudioClip` data class - Every item is bound to a `user` and `libraryItem` (and optionally `episode`) - Every item must have a `startTime` (>0) and `endTime` (>`startTime`) - Currently, there's no validation for `endTime` being beyond `libraryItem.duration` (potential improvement for the future?) - Every item must have a `title` (same as `AudioBookmarkObject`'s `title` property - Every item can have an optional `notes` field for lengthier information (such as, transcription, if/when it gets implemented) - Every item has a `createdAt` and `updatedAt` field, managed by the DBO itself - Added `AudioClip` to the sequelize Database handler - Added relevant CRUD functionality to `MeController` - Added routing to provide API via `ApiRouter` - Added database migration - Also covers importing existing bookmarks as Clips, with a default 10 second range defined from bookmark timestamp. Users then can freely edit the clips to cover the full range they want it to. (Potentially a callout on the UI would be beneficial to redirect the users and let them update all newly created Clips?) Future features/TODOs: - Implement ffmpeg call to extract audio into a specified folder - [ ] This can be either on-the-fly (whenever the user requests the download) - [ ] Or it can be on every update (whenever an AudioClip is saved/updated, the audio gets extracted). I prefer this solution as it means downloads are instantaneous - Add transcription to the AudioClip - And with the transcription, one can dig into a linked EPUB/eBook file and create a Kindle style highlight metadata file (or, any other format, I'm open to suggestions) - Add AI based cleanup. Selecting the exact precise range is often hard/impossible, but there are AI models out there that can analyse an audio file, and remove other voices from the beginning/end without clipping issues ## How have you tested this? My follow-up PR will implement the frontend changes (clips modal interface, although I am reworking the idea at the moment). The barebones UI test environment that I've created so far verified: - Standard CRUD operations work - API returns appropriate error messages when a bad request is sent - Logs show appropriate debug/warning/error logs Beyond this, I've also written test coverage for all new functionality wherever possible - which make up roughly 3/4 of this PR ## Screenshots Very barebones initial attempt at UI, more functional than good UX: <img width="2367" height="1328" alt="image" src="https://github.com/user-attachments/assets/2f6745c8-3cf1-4fb1-bdc7-d1de9ce3a656" /> UI is _not_ part of this PR! --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2026-04-25 00:19:25 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#4360
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?