zeba_academy_duration

A lightweight, dependency-free Dart package for converting, formatting, and working with Duration values.

zeba_academy_duration provides simple utilities for:

Human-readable duration text
Compact duration formatting
Digital HH:MM:SS formatting
MM:SS formatting
Seconds, minutes, hours, and milliseconds conversion
Decimal time conversion
Zero-duration handling
Negative-duration handling
Common duration constants

Built with a simple API and designed to work well in Flutter and Dart projects.

Features

✅ Human-readable duration formatting
✅ Compact duration formatting
✅ Digital HH:MM:SS formatting
✅ Digital MM:SS formatting
✅ Seconds → Duration
✅ Minutes → Duration
✅ Hours → Duration
✅ Milliseconds → Duration
✅ Duration → seconds
✅ Duration → minutes
✅ Duration → hours
✅ Duration → milliseconds
✅ Whole-unit conversions
✅ Zero-duration support
✅ Negative-duration support
✅ Decimal input support
✅ No runtime dependencies
✅ Pure Dart implementation
✅ Fully tested
✅ GPL-3.0 licensed

Installation

Add zeba_academy_duration to your pubspec.yaml:

dependencies:
  zeba_academy_duration: ^0.1.0

Then run:

flutter pub get

Or:

dart pub get

Import

import 'package:zeba_academy_duration/zeba_academy_duration.dart';

Quick Start

import 'package:zeba_academy_duration/zeba_academy_duration.dart';

void main() {
  const duration = Duration(
    hours: 2,
    minutes: 15,
    seconds: 30,
  );

  print(DurationFormatter.readable(duration));
  print(DurationFormatter.compact(duration));
  print(DurationFormatter.digital(duration));
  print(DurationFormatter.minutesAndSeconds(duration));
}

Output:

2 hours, 15 minutes, 30 seconds
2h 15m 30s
02:15:30
135:30

DurationFormatter

DurationFormatter provides display-oriented formatting utilities.

`readable()`

Converts a Duration into human-readable text.

final duration = Duration(
  hours: 2,
  minutes: 15,
  seconds: 30,
);

final result = DurationFormatter.readable(duration);

print(result);

Output:

2 hours, 15 minutes, 30 seconds

Singular values

final result = DurationFormatter.readable(
  const Duration(
    hours: 1,
    minutes: 1,
    seconds: 1,
  ),
);

print(result);

Output:

1 hour, 1 minute, 1 second

Zero-valued units are automatically omitted.

DurationFormatter.readable(
  const Duration(hours: 2),
);

Output:

2 hours

`compact()`

Creates a short human-readable representation.

final result = DurationFormatter.compact(
  const Duration(
    hours: 2,
    minutes: 15,
    seconds: 30,
  ),
);

print(result);

Output:

2h 15m 30s

Examples:

DurationFormatter.compact(
  const Duration(hours: 2),
);
// 2h

DurationFormatter.compact(
  const Duration(minutes: 15),
);
// 15m

DurationFormatter.compact(
  const Duration(seconds: 30),
);
// 30s

`digital()`

Formats a duration as HH:MM:SS.

final result = DurationFormatter.digital(
  const Duration(
    hours: 2,
    minutes: 5,
    seconds: 9,
  ),
);

print(result);

Output:

02:05:09

Values are automatically padded with leading zeroes.

DurationFormatter.digital(
  const Duration(
    hours: 1,
    minutes: 2,
    seconds: 3,
  ),
);

Output:

01:02:03

This format is useful for:

Timers
Stopwatches
Video players
Audio players
Exercise trackers
Countdown displays

`minutesAndSeconds()`

Formats a duration as MM:SS.

final result = DurationFormatter.minutesAndSeconds(
  const Duration(
    minutes: 5,
    seconds: 9,
  ),
);

print(result);

Output:

05:09

Hours are converted into total minutes:

DurationFormatter.minutesAndSeconds(
  const Duration(
    hours: 1,
    minutes: 5,
    seconds: 9,
  ),
);

Output:

65:09

This is especially useful for media players and countdown timers where hours aren't displayed separately.

DurationUtils

DurationUtils provides conversion utilities.

`fromSeconds()`

Create a Duration from seconds.

final duration = DurationUtils.fromSeconds(90);

print(duration);

Result:

0:01:30.000000

Decimal values are supported:

final duration = DurationUtils.fromSeconds(1.5);

print(duration.inMilliseconds);

Output:

`fromMinutes()`

Create a Duration from minutes.

final duration = DurationUtils.fromMinutes(5);

print(duration);

Decimal values are supported:

final duration = DurationUtils.fromMinutes(1.5);

print(duration.inSeconds);

Output:

`fromHours()`

Create a Duration from hours.

final duration = DurationUtils.fromHours(2);

print(duration);

Decimal values are supported:

final duration = DurationUtils.fromHours(1.5);

print(duration.inMinutes);

Output:

`fromMilliseconds()`

Create a Duration directly from milliseconds.

final duration = DurationUtils.fromMilliseconds(1500);

print(duration);

Result:

0:00:01.500000

Duration Conversion

`toSeconds()`

Returns the total duration in seconds as a double.

const duration = Duration(
  hours: 2,
  minutes: 30,
  seconds: 15,
);

final seconds = DurationUtils.toSeconds(duration);

print(seconds);

Output:

9015.0

`toMinutes()`

Returns the total duration in minutes.

const duration = Duration(
  hours: 2,
  minutes: 30,
  seconds: 15,
);

final minutes = DurationUtils.toMinutes(duration);

print(minutes);

Output:

150.25

`toHours()`

Returns the total duration in hours.

const duration = Duration(
  hours: 2,
  minutes: 30,
  seconds: 15,
);

final hours = DurationUtils.toHours(duration);

print(hours);

Output:

2.504166666666667

Because Dart double values use floating-point representation, tiny precision differences may occur.

`toMilliseconds()`

Returns the total duration in milliseconds.

const duration = Duration(
  hours: 2,
  minutes: 30,
  seconds: 15,
);

final milliseconds = DurationUtils.toMilliseconds(duration);

print(milliseconds);

Output:

Whole Unit Conversions

When only complete units are required, use the whole-unit methods.

`wholeSeconds()`

final seconds = DurationUtils.wholeSeconds(
  const Duration(
    minutes: 2,
    seconds: 30,
  ),
);

print(seconds);

Output:

`wholeMinutes()`

final minutes = DurationUtils.wholeMinutes(
  const Duration(
    hours: 2,
    minutes: 30,
    seconds: 15,
  ),
);

print(minutes);

Output:

The remaining seconds are discarded.

`wholeHours()`

final hours = DurationUtils.wholeHours(
  const Duration(
    hours: 2,
    minutes: 30,
  ),
);

print(hours);

Output:

The remaining minutes and seconds are discarded.

Zero Duration

The package provides explicit zero-duration handling.

Readable

DurationFormatter.readable(Duration.zero);

Output:

0 seconds

Compact

DurationFormatter.compact(Duration.zero);

Output:

0s

Digital

DurationFormatter.digital(Duration.zero);

Output:

00:00:00

Minutes and seconds

DurationFormatter.minutesAndSeconds(Duration.zero);

Output:

00:00

Negative Duration

Negative durations are supported.

const duration = Duration(seconds: -90);

print(DurationFormatter.readable(duration));
print(DurationFormatter.compact(duration));
print(DurationFormatter.digital(duration));

Output:

-1 minute, 30 seconds
-1m 30s
-00:01:30

This is useful when calculating differences between timestamps or tracking elapsed/remaining values.

DurationConstants

The package exposes commonly used duration constants.

DurationConstants.millisecondsPerSecond
DurationConstants.secondsPerMinute
DurationConstants.minutesPerHour
DurationConstants.secondsPerHour
DurationConstants.millisecondsPerMinute
DurationConstants.millisecondsPerHour

Example:

print(DurationConstants.secondsPerMinute);
// 60

print(DurationConstants.secondsPerHour);
// 3600

print(DurationConstants.millisecondsPerHour);
// 3600000

API Overview

API	Purpose
`DurationFormatter.readable()`	Human-readable duration
`DurationFormatter.compact()`	Compact duration
`DurationFormatter.digital()`	`HH:MM:SS`
`DurationFormatter.minutesAndSeconds()`	`MM:SS`
`DurationUtils.fromSeconds()`	Seconds → Duration
`DurationUtils.fromMinutes()`	Minutes → Duration
`DurationUtils.fromHours()`	Hours → Duration
`DurationUtils.fromMilliseconds()`	Milliseconds → Duration
`DurationUtils.toSeconds()`	Duration → seconds
`DurationUtils.toMinutes()`	Duration → minutes
`DurationUtils.toHours()`	Duration → hours
`DurationUtils.toMilliseconds()`	Duration → milliseconds
`DurationUtils.wholeSeconds()`	Complete seconds
`DurationUtils.wholeMinutes()`	Complete minutes
`DurationUtils.wholeHours()`	Complete hours
`DurationConstants`	Common time constants

Practical Examples

Countdown Timer

final remaining = const Duration(
  minutes: 4,
  seconds: 35,
);

print(DurationFormatter.digital(remaining));

Output:

00:04:35

Video Duration

final videoDuration = const Duration(
  hours: 1,
  minutes: 24,
  seconds: 18,
);

print(DurationFormatter.readable(videoDuration));

Output:

1 hour, 24 minutes, 18 seconds

Compact UI Label

final duration = const Duration(
  hours: 3,
  minutes: 20,
);

final label = DurationFormatter.compact(duration);

print(label);

Output:

3h 20m

Testing

Run the complete test suite:

flutter test

Run static analysis:

flutter analyze

Run the package publishing validation:

flutter pub publish --dry-run

The package is designed to be fully testable without requiring network access or external services.

Project Structure

zeba_academy_duration/
├── lib/
│   ├── src/
│   │   ├── duration_constants.dart
│   │   ├── duration_formatter.dart
│   │   └── duration_utils.dart
│   └── zeba_academy_duration.dart
├── test/
│   └── zeba_academy_duration_test.dart
├── CHANGELOG.md
├── LICENSE
├── README.md
├── analysis_options.yaml
└── pubspec.yaml

Requirements

Dart SDK >=3.12.0
Flutter SDK compatible with the Dart SDK
No additional runtime dependencies

Why Use This Package?

Working with Dart's built-in Duration class is straightforward, but applications frequently need repeated formatting and conversion logic.

Instead of writing:

duration.inHours
duration.inMinutes % 60
duration.inSeconds % 60

throughout your application, you can use:

DurationFormatter.readable(duration);

or:

DurationFormatter.digital(duration);

This keeps presentation and conversion code consistent across your project.

Design Philosophy

zeba_academy_duration follows a few simple principles:

Simple API — Easy-to-discover static methods.
No unnecessary dependencies — Pure Dart implementation.
Predictable output — Consistent formatting.
Safe zero handling — Explicit zero-duration behavior.
Negative duration support — Useful for time differences.
Reusable utilities — Suitable for Flutter and Dart projects.
Testable — Core functionality is covered by automated tests.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You may use, modify, and redistribute this software under the terms of the GNU GPL v3.0.

See the LICENSE file included with this project for the complete license text.

For more information about the GNU General Public License:

https://www.gnu.org/licenses/gpl-3.0

About Me

✨ I’m Sufyan bin Uzayr, an open-source developer passionate about building and sharing meaningful projects.

You can learn more about me and my work at sufyanism.com or connect with me on LinkedIn.

Zeba Academy

Your all-in-one learning hub!

🚀 Explore courses and resources in coding, tech, and development at zeba.academy and code.zeba.academy.

Empower yourself with practical skills through curated tutorials, real-world projects, and hands-on experience. Level up your tech game today! 💻✨

Zeba Academy is a learning platform dedicated to coding, technology, and development.

➡ Visit our main site: zeba.academy

➡ Explore hands-on courses and resources: code.zeba.academy

➡ Check out our YouTube for more tutorials: zeba.academy

➡ Follow us on Instagram: zeba.academy

Contributing

Contributions, suggestions, bug reports, and improvements are welcome.

Before submitting a pull request:

Make your changes.
Add or update tests.
Run flutter test.
Run flutter analyze.
Ensure the public API remains documented.
Submit a clear pull request describing the change.

Please keep contributions focused, lightweight, and consistent with the package's existing API design.

Support

If you find a bug or have a feature request, please open an issue in the project's repository.

When reporting a bug, include:

Dart/Flutter version
Package version
Expected behavior
Actual behavior
Minimal reproducible example

Thank You

Thank you for visiting and using zeba_academy_duration.

If this package helps your Flutter or Dart project, consider sharing it with other developers. ⭐

Built with Dart & Flutter by the Zeba Academy community.

zeba_academy_duration

Features

Installation

Import

Quick Start

DurationFormatter

readable()

Singular values

compact()

digital()

minutesAndSeconds()

DurationUtils

fromSeconds()

fromMinutes()

fromHours()

fromMilliseconds()

Duration Conversion

toSeconds()

toMinutes()

toHours()

toMilliseconds()

Whole Unit Conversions

wholeSeconds()

wholeMinutes()

wholeHours()

Zero Duration

Readable

Compact

Digital

Minutes and seconds

Negative Duration

DurationConstants

API Overview

Practical Examples

Countdown Timer

Video Duration

Compact UI Label

Testing

Project Structure

Requirements

Why Use This Package?

Design Philosophy

License

About Me

Zeba Academy

Your all-in-one learning hub!

Contributing

Support

Thank You

Libraries

zeba_academy_time_utils package

`readable()`

`compact()`

`digital()`

`minutesAndSeconds()`

`fromSeconds()`

`fromMinutes()`

`fromHours()`

`fromMilliseconds()`

`toSeconds()`

`toMinutes()`

`toHours()`

`toMilliseconds()`

`wholeSeconds()`

`wholeMinutes()`

`wholeHours()`