GGWavePlayerLib 1.0.0

GGWavePlayerLib

A simple and elegant NuGet package that provides an easy way to play and save GGWave audio by encoding text messages into sound waves, built with VB.NET but fully compatible with C# and F#.

📋 Description

GGWavePlayerLib encapsulates the GGWave encoding and audio playback logic from ggwave.net, eliminating the need for boilerplate code. With just a few lines of code, you can convert text messages into audio waves and play them through speakers or save them as WAV files.

Note: This library currently supports encoding text messages to audio waves. Decoding audio waves back into text messages is not supported at this time.

✨ Features

• Play GGWave Audio - Directly play encoded messages through system speakers
• Save to WAV Files - Export encoded audio to standard WAV format
• Multiple Sample Rates - Choose from 4 different quality levels
• Protocol Support - Support for various GGWave protocols (audible, ultrasound, dualtone, monotone, and custom)
• Encoding Options - Support for both ASCII and UTF-8 text encoding
• Simple API - Clean, intuitive interface with minimal code required

🔧 Requirements

• .NET 8.0 or higher (works with C#, F# and VB.NET)
• Dependencies:
  • ggwave.net v0.2.1
  • NAudio v2.2.1

📦 Installation

Install the package via command line:

dotnet add package GGWavePlayerLib

Or using .NET CLI / Package Manager Console:

Install-Package GGWavePlayerLib

🚀 Quick Start

Playing GGWave Audio

Imports GGWavePlayerLib

' Play a simple message with default settings
GGWavePlayer.PlayGGWave("Hello world!", GGWaveRate.CDQuality)

' Play with custom protocol and UTF-8 encoding
GGWavePlayer.PlayGGWave("吃了吗，世界？",
    GGWaveRate.Professional, ProtocolId.AudibleNormal, useUtf8:=True)

Saving GGWave to WAV File

Imports GGWavePlayerLib

' Save a message to a WAV file
GGWavePlayer.SaveGGWave("Secret message", GGWaveRate.CDQuality, "output.wav")

' Save with custom settings
GGWavePlayer.SaveGGWave(
    "Important data", GGWaveRate.Professional, "important.wav",
    ProtocolId.AudibleFastest, useUtf8:=False
)

📚 API Reference

GGWaveRate Enum

Represents the audio sample rate for GGWave encoding. Higher rates provide better audio quality but require more bandwidth.

ProtocolId Enum

Represents the protocol ID for GGWave encoding. These values are wrapped from the original ggwave.net.Native.ProtocolId enum.

Audible Protocols:

• AudibleNormal - Standard audible transmission (default)
• AudibleFast - Faster audible transmission
• AudibleFastest - Fastest audible transmission

Ultrasound Protocols:

• UltrasoundNormal - Standard ultrasound transmission
• UltrasoundFast - Faster ultrasound transmission
• UltrasoundFastest - Fastest ultrasound transmission

Dualtone Protocols:

• DualtoneNormal - Standard dual-tone transmission
• DualtoneFast - Faster dual-tone transmission
• DualtoneFastest - Fastest dual-tone transmission

Monotone Protocols:

• MonotoneNormal - Standard monotone transmission
• MonotoneFast - Faster monotone transmission
• MonotoneFastest - Fastest monotone transmission

Custom Protocols:

• Custom0 through Custom9 - Custom protocol configurations

PlayGGWave Method

Plays the GGWave audio for the given message through the system speakers.

Public Sub PlayGGWave(
    message As String, waveRate As GGWaveRate,
    Optional protocolId As ProtocolId = ProtocolId.AudibleNormal,
    Optional useUtf8 As Boolean = False
)

Parameters:

• message - The text message to encode and play
• waveRate - The sample rate for audio encoding (see GGWaveRate enum)
• protocolId - The GGWave protocol to use (default: AudibleNormal)
• useUtf8 - Whether to use UTF-8 encoding instead of ASCII (default: False)

SaveGGWave Method

Saves the GGWave audio for the given message to a WAV file.

Public Sub SaveGGWave(
    message As String, waveRate As GGWaveRate, filePath As String,
    Optional protocolId As ProtocolId = ProtocolId.AudibleNormal,
    Optional useUtf8 As Boolean = False
)

Parameters:

• message - The text message to encode and save
• waveRate - The sample rate for audio encoding (see GGWaveRate enum)
• filePath - The path where the WAV file will be saved
• protocolId - The GGWave protocol to use (default: AudibleNormal)
• useUtf8 - Whether to use UTF-8 encoding instead of ASCII (default: False)

💡 Usage Tips

1. Choose the Right Sample Rate:

   • Use StandardLow or StandardHigh for basic applications where file size matters
   • Use CDQuality for most general-purpose applications
   • Use Professional for high-fidelity applications

2. Protocol Selection:

   • AudibleNormal is the default and works well for most cases
   • Use Fast or Fastest variants for quicker transmission
   • Use Ultrasound protocols for applications requiring inaudible transmission
   • Use Dualtone or Monotone for specific hardware compatibility

3. Encoding:

   • Use ASCII (useUtf8:=False) for English text and basic characters
   • Use UTF-8 (useUtf8:=True) for international characters and emojis

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions, please open an issue on the project repository.

🙏 Acknowledgments

• Built on top of the excellent ggwave.net library
• Audio playback powered by NAudio
• Based on the GGWave project by Georgi Gerganov