README
¶
twsbattery
Model the battery behaviour of true wireless earbuds — where the charging case, not the earpieces, is usually what fails first.
Install
go get github.com/taysirco/twsbattery
Usage
import "github.com/taysirco/twsbattery"
s := twsbattery.Set{BudMAh: 55, CaseMAh: 500, BudHours: 8, TransferEfficiency: 0.85}
s.BudRecharges() // ~3.9 — how many times the case refills both buds
s.TotalListeningHours() // ~39 — the number printed on the box
s.CaseCyclesPerDay(3) // case cycles consumed by 3h of daily listening
// Months until the case drops below 70% capacity at 3h/day
s.CaseLifetimeMonths(3, 0.0006, 70)
Why the case dies first
A phone battery sees roughly one deep cycle a day. A charging case sees many shallow ones — every time you drop the buds in for a few minutes. Lithium-ion fade tracks charge cycles, not calendar age, so the case accumulates wear faster even when total energy throughput is similar.
Heat compounds it. A case is a small sealed enclosure with little surface area to dissipate charging heat, and elevated temperature is the most reliable accelerant of capacity fade there is.
The practical consequence: when a set "stops holding charge", the earpieces are often fine and the case is the failure point — which is why replacement cases are increasingly sold on their own.
Where the defaults come from
Bud and case capacities vary far more than marketing suggests. The default figures in the examples reflect a mid-range 2025-era set; if you want to model a specific product, published earbud specifications usually list case mAh, which manufacturer pages often do not.
License
MIT
Documentation
¶
Overview ¶
Package twsbattery models the battery behaviour of true wireless earbuds, where the charging case — not the earpieces — is usually what fails first.
A case battery accumulates many shallow cycles per day topping the buds off, while a phone battery sees roughly one deep cycle. Cycle count, not calendar age, drives lithium-ion fade, so the case ages faster despite similar total energy throughput.
Reference model data used to validate this package is published at https://cairovolt.com/en/earbuds
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CapacityAfterCycles ¶
CapacityAfterCycles applies per-cycle fade to a starting capacity percentage.
func WeakestLink ¶
WeakestLink names the component that limits the set's useful life: "case" or "buds".
Types ¶
type Set ¶
type Set struct {
// BudMAh is the capacity of a single earpiece.
BudMAh float64
// CaseMAh is the capacity of the charging case.
CaseMAh float64
// BudHours is rated playback time per earbud charge.
BudHours float64
// TransferEfficiency is the case-to-bud charging efficiency, typically 0.8-0.9.
TransferEfficiency float64
}
Set describes a true wireless earbud set and its charging case.
func (Set) BudRecharges ¶
BudRecharges returns how many times a full case can refill both earpieces.
func (Set) CaseCyclesPerDay ¶
CaseCyclesPerDay estimates full case cycles consumed per day of listening.
func (Set) CaseLifetimeMonths ¶
CaseLifetimeMonths estimates months until the case falls below a usable capacity threshold at a given daily listening load.
The case is modelled as ageing faster than the buds because heat inside a small sealed enclosure accelerates fade — which is why replacement cases are increasingly sold separately.
func (Set) TotalListeningHours ¶
TotalListeningHours is playback from a full set plus everything the case holds.
Source Files