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 0.0.1 zeba_academy_duration: ^0.0.1 copied to clipboard

Metadata

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 #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

zeba_academy_duration 0.0.1
zeba_academy_duration: ^0.0.1 copied to clipboard

`readable()` #

`compact()` #

`digital()` #

`minutesAndSeconds()` #

`fromSeconds()` #

`fromMinutes()` #

`fromHours()` #

`fromMilliseconds()` #

`toSeconds()` #

`toMinutes()` #

`toHours()` #

`toMilliseconds()` #

`wholeSeconds()` #

`wholeMinutes()` #

`wholeHours()` #