whisper-dvr.texi

\input texinfo   @c -*- texinfo -*-
@c %**start of header
@setfilename whisper-dvr.info
@settitle whisper-dvr User Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@copying
This manual is for whisper-dvr (version 0.2.0).

Copyright @copyright{} 2024-2025 Blaine Mooers.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@end quotation
@end copying

@dircategory Emacs
@direntry
* whisper-dvr: (whisper-dvr).   Transcribe audio files from DVR with whisper.el.
@end direntry

@titlepage
@title whisper-dvr User Manual
@subtitle Transcribe audio files from DVR with whisper.el
@author Blaine Mooers
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top whisper-dvr

whisper-dvr is an Emacs package that provides a convenient interface
for transcribing audio files from a digital voice recorder using
whisper.el.

@insertcopying
@end ifnottex

@menu
* Introduction::        Overview of whisper-dvr
* Installation::        How to install whisper-dvr
* Configuration::       Configuring whisper-dvr
* Usage::               How to use whisper-dvr
* Customization::       Available customization options
* Troubleshooting::     Common issues and solutions
* Contributing::        How to contribute
* License::             License information
* Index::               Complete index
@end menu

@node Introduction
@chapter Introduction

whisper-dvr is a companion package for whisper.el that simplifies the
workflow of transcribing audio files from a digital voice recorder
(DVR).

@section Features

@itemize @bullet
@item
Lists all audio files from your DVR directory
@item
Displays file information (name, size, modification time)
@item
Supports multiple audio formats (MP3, WAV, M4A)
@item
Integrates seamlessly with whisper.el for transcription
@item
Inserts transcription directly at point
@end itemize

@section Requirements

@itemize @bullet
@item
Emacs 27.1 or later
@item
whisper.el (@url{https://github.com/natrys/whisper.el})
@item
A working whisper.cpp installation (handled by whisper.el)
@end itemize

@node Installation
@chapter Installation

@section Using straight.el
@cindex installation, straight.el

@lisp
(use-package whisper-dvr
  :straight (whisper-dvr :type git :host github
                         :repo "MooersLab/whisper-dvr")
  :after whisper
  :bind ("C-c w d" . whisper-dvr))
@end lisp

@section Manual Installation
@cindex installation, manual

@enumerate
@item
Clone the repository:

@example
git clone https://github.com/MooersLab/whisper-dvr.git
@end example

@item
Add to your load-path:

@lisp
(add-to-list 'load-path "/path/to/whisper-dvr")
(require 'whisper-dvr)
@end lisp
@end enumerate

@node Configuration
@chapter Configuration
@cindex configuration

Basic configuration:

@lisp
(setq whisper-dvr-directory "/Volumes/IC RECORDER/REC_FILE/FOLDER01")
(global-set-key (kbd "C-c w d") #'whisper-dvr)
@end lisp

Set the directory to match where your DVR mounts on your system.

@node Usage
@chapter Usage

@section Basic Usage
@cindex usage, basic

@enumerate
@item
Connect your digital voice recorder to your computer.

@item
Open an Emacs buffer where you want the transcription inserted.

@item
Run @kbd{M-x whisper-dvr} or press @kbd{C-c w d}.

@item
Select an audio file from the completion list.

@item
Wait for the transcription to complete.
@end enumerate

@section Changing the DVR Directory
@cindex directory, changing
@findex whisper-dvr-set-directory

If your DVR is mounted at a different location:

@example
M-x whisper-dvr-set-directory RET /path/to/dvr RET
@end example

@section Interactive Commands
@cindex commands

@table @code
@item whisper-dvr
@findex whisper-dvr
List audio files from the DVR directory and transcribe the selected file.
Default keybinding: @kbd{C-c w d}.

@item whisper-dvr-set-directory
@findex whisper-dvr-set-directory
Interactively set the DVR directory path.
@end table

@node Customization
@chapter Customization

@section whisper-dvr-directory
@vindex whisper-dvr-directory
@cindex customization, directory

The directory path where your DVR stores recordings.

Default: @code{"/Volumes/IC RECORDER/REC_FILE/FOLDER01"}

@lisp
(setq whisper-dvr-directory "/your/dvr/path")
@end lisp

@section whisper-dvr-file-extensions
@vindex whisper-dvr-file-extensions
@cindex customization, file extensions

List of audio file extensions to include when listing files.

Default: @code{'("mp3" "wav" "m4a")}

@lisp
(setq whisper-dvr-file-extensions '("mp3" "wav" "m4a" "ogg"))
@end lisp

@node Troubleshooting
@chapter Troubleshooting
@cindex troubleshooting

@section DVR directory does not exist
@cindex error, directory not found

Ensure your DVR is connected and mounted.  Check the mount path with:

@example
ls /Volumes/  # macOS
ls /media/    # Linux
@end example

@section No audio files found
@cindex error, no files found

Verify that:
@itemize @bullet
@item
The directory path is correct
@item
The directory contains files with supported extensions
@item
File permissions allow reading
@end itemize

@section Transcription starts recording instead of transcribing
@cindex error, wrong number of arguments
@cindex whisper-file, API change

This was a bug in versions prior to 0.2.0.  The issue occurred because
@code{whisper-file} in whisper.el changed from accepting a file path
argument to being an interactive-only function.

Update to version 0.2.0 or later, which correctly calls @code{whisper-run}
with the file path directly.

@node Contributing
@chapter Contributing
@cindex contributing

Contributions are welcome!

@enumerate
@item
Fork the repository on GitHub
@item
Create a feature branch
@item
Make your changes
@item
Run tests: @code{make test}
@item
Submit a pull request
@end enumerate

@node License
@chapter License

whisper-dvr is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

@node Index
@unnumbered Index

@section Concept Index
@printindex cp

@section Function Index
@printindex fn

@section Variable Index
@printindex vr

@bye