Git Product home page Git Product logo

debatekeeper's Introduction

Debatekeeper — a timekeeper for debate speeches

Debatekeeper is an Android app that times speeches in debates and rings bells automatically at the correct times. It supports most parliamentary styles of debating, including British Parliamentary, Australasian, Asian, Australian, American Parliamentary, certain forms of Canadian Parliamentary and all New Zealand styles.

The app rings a bell, vibrates and/or flashes the screen white (or any combination of the three) at bell times. It also rings overtime bells, which are configurable.

A small amount of documentation for this app is at https://github.com/czlee/debatekeeper/wiki/.

The app is available on the Google Play Store.

What is the status of this app?

Version 1.4 was rolled out in June 2023. This update was mostly just to comply with Android's target API level requirements, so that the app doesn't get pulled from the Play Store. I don't intend to do any other work on Debatekeeper, other than maintaining the new online formats repository (whose main purpose is to make it easier to accept new debate formats without having to update the app) and further target API upd

I would love for someone new to pick up this project and run with it. It's licensed under the GPLv3, so any prospective developer would be bound by those licensing terms. You're welcome to contact me if you have any questions. See the notes for prospective developers below.

Licence

This app (and all source code, with exceptions noted below) is licensed under the GNU General Public Licence version 3. You can find a copy of this licence in the "licence.txt" file, or go to http://www.gnu.org/licenses/gpl-3.0.html.

The exception is the bell sounds. I bought the single bell sound from SFXSource (which appears to be now defunct), so I can't make it freely available. If you want to contribute and need this file, get in touch with me.

Adding debate styles

New debate styles should be submitted to the online debate formats repository at https://github.com/czlee/debatekeeper-formats. Instructions are in that repository.

I've written a page on how to write a debate format XML file. But it's probably easiest in the first instance to look in the formats repository for the XML files there, and modify one of those.

This app doesn't do the public forum, Lincoln-Douglas or policy debate styles. There are other Android apps that do this. The reason this app can't currently do this is that it doesn't currently support preparation time that can be used by teams between speeches at their election. A discussion of this is in issue #6.

Notes for prospective developers

I don't intend to work on this app beyond version 1.3 (October 2021), so if you're interested in helping with development, I'd love for you to dive in and possibly take over the project. Contact me if you want to discuss anything, or feel free to just fork the repository and get going.

Note: The master branch has legacy support code for version 1.3 that should be removed in the next version. I've done this on the remove-legacy branch, so for any non-minor development, please start from that branch (and merge it into master).

Files you need to build this project

To build this project, you'll need to:

  1. Check out this repository (and put it somewhere useful)

  2. Add the bell sounds, called desk_bell.mp3, desk_bell_double.mp3 and desk_bell_triple.mp3, all to the app/src/main/res/raw/ directory. The app won't build without a sound file of some sort there. Any sound file will do. I'm happy to provide the file to interested developers, on the understanding that it is not available under a free-distribution license (as discussed above)—contact me at the details below. Of course, future developers may also use other sounds, including more freely available ones, if they can find a satisfactory one.

Sound file specifications

If you wish to use your own sound files for the desk_bell*.mp3 files, here is some information about them:

  • The sound is a desk bell (as the name suggests), also known as a counter bell or call bell.
  • The original desk_bell.mp3 sound is about 2 seconds long, but this shouldn't in principle matter; there is code that stops any existing playback if a new one needs to be started.
  • The desk_bell_double.mp3 and desk_bell_triple.mp3 sounds are just the desk_bell.mp3 sound, but repeated at an interval of 0.5 seconds. Any sound editing tool should be able to do this; I used Audacity. The purpose of these files is just to make the interval more predictable and to avoid abrupt audio stops for common multiple-bell cases.

Publishing to the Play Store

If you work on a significant update, I'll encourage you to list it under a separate Play Store listing on your own account. To do this, you'll need to change the package name from net.czlee.debatekeeper to something else. Feel free to rename/rebrand it if you like. Don't forget that, under the GPL-3.0, you're required to make your code publicly available. Please credit me in your distribution (e.g. in the store listing).

For minor updates, I might consider pull requests and releasing it under the existing Play Store listing. Just be aware that some pull requests have sat around for several years before I got a chance to look at them, and this is likely to be longer in the future.

Please don't hesitate to email me if you have any questions about how to proceed with this. I'm likely to take forever with reviewing code, but I should be able to respond to emails about a developer transition much more quickly.

Contacting the author

You can find my e-mail address by checking out this repository and looking at the commit authors, or alternatively message me on Facebook (czlee) or Twitter (@czczlee).

debatekeeper's People

Contributors

czlee avatar philcaonz avatar pmcheng avatar poussinou avatar res2k avatar tswsl1989 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

debatekeeper's Issues

Spanish Academic - not sure why I'm having an error

This is my first XML I've made in my life and I copied/pasted other style to use it as a template. Obviously I'm missing something

 
<?xml version='1.0' encoding='UTF-8'?>
<debate-format schema-version="2.1">
  <name>Spanish Academic</name>
  <short-name>ACAD</short-name>
  <info>
    <region>Spain and Latin America</region>
    <level>University</level>
    <used-at>Spanish Debate Associations</used-at>
    <description>4 vs 4, POIs allowed, I: 4 min, 1R: 5 min, 2R: 5 min, C: 3 min</description>
  </info>
  <speech-types>
    <speech-type ref="introductory" length="4:00" first-period="normal">
      <bell time="1:00" number="1" next-period="pois-allowed"/>
      <bell time="3:00" number="1" next-period="warning"/>
      <bell time="finish" number="2" next-period="overtime"/>
    </speech-type>
    <speech-type ref="refutation" length="5:00" first-period="normal">
      <bell time="1:00" number="1" next-period="pois-allowed"/>
      <bell time="4:00" number="1" next-period="warning"/>
      <bell time="finish" number="2" next-period="overtime"/>
    </speech-type>
    <speech-type ref="conclusion" length="3:00" first-period="normal">
      <bell time="1:00" number="1" next-period="pois-allowed"/>
      <bell time="2:00" number="1" next-period="warning"/>
      <bell time="finish" number="2" next-period="overtime"/>
    </speech-type>
  </speech-types>
  <speeches>
    <speech type="introductory">
      <name>In Favour - Introductory</name>
    </speech>
    <speech type="introductory">
      <name>Against - Introductory</name>
    </speech>
    <speech type="refutation">
      <name>In Favour - First Refutation</name>
    </speech>
    <speech type="refutation">
      <name>Against - First Refutation</name>
    <speech type="refutation">
      <name>In Favour - Second Refutation</name>
    </speech>
    <speech type="refutation">
      <name>Against - Second Refutation</name>
    </speech>
    <speech type="conclusion">
      <name>Against - Conclusion</name>
    </speech>
    <speech type="conclusion">
      <name>In Favour - Conclusion</name>
    </speech>
  </speeches>
</debate-format>

Add profiles feature

Add feature: profiles are combinations of settings that can be saved and recalled as an entire set. Include "debater" and "adjudicator" profiles by default.

Add "Share" feature for debate styles

It would probably work like this:

  • A "Share" button associated with any debate style would send the XML file (as the raw file) via whatever means, using a generic Intent
  • An intent filter would be added for all XML files, that give the option to be opened by Debatekeeper, and after checking that the first element is <debate-format> or <debateformat>, all it would do is copy it to the /debatekeeper directory
  • An "Import" item from the menu would launch a file chooser, and copy it to the /debatekeeper directory

Either that, or we invent a new file extension just for transfers. Would probably prefer not to do it this way though.

Probably not worth having files exchanged in a way hidden to the user.

New icon

So, I made this icon, which I think it goes much better with the current design of the app since it uses the Google Material Design notification icon as a bell and not the one drawn in the current logo.

Of course this is just a suggestion and I still keep the SVG file in case you want me to change anything.

My proposal

Auto-rotation in FormatChooserActivity invokes weird scrolling

When the screen orientation changes while in FormatChooserActivity, the ListView scrolls to some other position. This is probably caused by the smoothScrollToPosition line in onCreate().

Sometimes it appears to be the original selection, but sometimes it's unclear how it arrives at the position it does.

Auto-rotation in FormatChooserActivity invokes weird scrolling

When the screen orientation changes while in FormatChooserActivity, the ListView scrolls to some other position. This is probably caused by the smoothScrollToPosition line in onCreate().

Sometimes it appears to be the original selection, but sometimes it's unclear how it arrives at the position it does.

Add profiles feature

Add feature: profiles are combinations of settings that can be saved and recalled as an entire set. Include "debater" and "adjudicator" profiles by default.

Add American-style preparation time

Suggested approach: The main counter always represents the total prep time elapsed (including all stages), and the prep time used in this stage is a new set of methods. The brainwork is all done in DebateManager, i.e. DebatePhaseManager doesn't require modification.

  • DebateManager#resetActivePhase() would discriminate prep times apart and not call DebatePhaseManager#reset() if it is a distributed prep time phase, but instead just set stop the timer and set the current time to the total prep time allowed less the sum of all other stages.
  • Prep time phases are specified by <prep team="affirmative"> in the XML file, and as far as the app is concerned are just numbered from 0.
  • Would need to override the period info description with the name of the next speaker.
  • Would need new member mPrepTImes being a map of enums (for the teams) to a list of times.
  • You can always calculate the time for this phase in DebateManager by subtracting the sum of all other phases from the time elapsed in this phase.
  • Time elapsed in this phase is shown in smaller font where the POI button normally is, and always counts up, never down as that would make no sense.
  • No need to worry about length/overtime from GUI perspective, as these don't change. What changes is the initial value of the timer, as it is set to the time remaining of all prep time stages.
  • However, will need to update controls so that "Start" is displayed when the time remaining is equal to the total time available minus the time used in other prep time stages.

Then the phase index logic will have to be written to accommodation for distributed prep time.

Auto-advance

Hi! I have read through the wiki and can't seem to determine if there's an auto-advance feature for speeches. Essentially, a modification of this line:
<bell time="finish" number="2" next-period="normal"/>
I can't determine if there's a type of "next-period" that will send the program on to the next speech without manual intervention by the user instead of having it stay on the current speech and sit in an additional time queue. Is this possible?

Make downloads searchable or filterable

Currently, the downloads screen just downloads a single list of everything, and the user has to scroll through the list to find the one they want. At the beginning this is probably fine, but if the online repository grows, this might become unwieldy. In that case, it might be nice to allow the user to filter the downloads list based on search terms or something like that.

Document bell sound "metrics" to aid future replacement

The currently used bell sound was obtained from a commercial source with probably restricted usage rights.
Contributors and/or forkers may want to use a sound that is licensed liberally (e.g. from https://freesound.org/, a repository of Creative Commons licensed sounds), or just some sound file.

Either way, in order to pick or create suitable sound files, it would be helpful to know some important "metrics":

  • Length of bell sound and/or sound file
  • Interval between bells for "2x, 3x" copies

I suggest to add these to the README part where the bell sound provision is discussed.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.